没有不值得去解决的问题,也没有不值得去学习的技术!

The “A Tour of Go” Multilingual Translation Project: Public UI Localization Is Complete

Figure 2: Chinese lesson page and the localized editor control area

作者:

在

In the previous phase, I completed the translation of all lesson content for A Tour of Go in Simplified Chinese and finished the pre-release global quality audit.

The current official release projection is:

Plaintext
ready=103
pending=0
blocked=0

All 103 pages have entered ready.

However, completing the lesson content translation does not mean a truly releasable Chinese version of the Tour is complete.

After actually opening the pages, besides the lesson content, there is still a lot of public interface text belonging to the Tour itself, such as:

  • Page titles;
  • The top A Tour of Go;
  • The lesson list page title;
  • Module names and descriptions;
  • Table of contents;
  • Syntax, Imports, Run, Format, Reset in the editor;
  • Run status;
  • Feedback entry;
  • Theme toggle accessibility text.

If these contents remain in English, the final result will be a half-finished state where “the lessons are in Chinese, but the shell is still in English.”

Therefore, after all 103 lesson pages were completed, I did not immediately proceed to release. Instead, I added a separate phase:

Public UI localization.

As of today, this phase is finally complete.


1. Lesson content and public UI were not translated together from the start

Early in this project, a principle was established:

Lesson content and public UI text should be maintained separately.

The lesson content comes from the official .article file, which has its own rather unique present structure and also involves:

  • .play;
  • Inline code;
  • Links;
  • Static preformatted code;
  • Emphasis;
  • Conditional sections;
  • Directives;
  • Page structure comparisons.

Therefore, the lesson content uses a workflow where the “complete lesson page serves as the minimum translation unit.”

The public UI is completely different.

It is mainly scattered across:

Plaintext
_content/tour/template/
_content/tour/static/partials/
_content/tour/static/js/
_content/js/playground.js
internal/tour/

If these UI texts were forced into the .article translation system, it would mix two completely different problems.

Therefore, a separate directory was created for the public UI this time:

Plaintext
internal/tour/ui/
├── catalog.go
├── catalog_test.go
├── en.json
└── zh-CN.json

Among these:

  • en.json stores the English public UI corresponding to the frozen upstream;
  • zh-CN.json stores the Simplified Chinese public UI;
  • catalog.go handles loading and validation;
  • Go code compiles the language catalog into the program via go:embed.

The first phase still adheres to the original architectural direction:

Select a single language at build time / startup, without runtime dynamic language switching.

This is much simpler than developing a complete language-switching framework right now, and it better fits the actual needs of the current project.


2. The public UI catalog is not a simple “display English if Chinese is not found”

I deliberately made this part quite strict.

A common multilingual program might handle it like this:

Plaintext
Find zh-CN
→ Not found
→ Fallback to en

But for this project, I specifically do not want this behavior.

Because fallbacks can easily mask problems.

For example, if a new UI text is added in the future but the Chinese translation is forgotten:

Plaintext
English catalog has it
zh-CN catalog does not

If it automatically falls back, the page can still run normally, except an English sentence quietly appears.

If this is only discovered after the actual release, it is very difficult to guarantee completeness.

So the current approach is:

No English fallback is provided.

If zh-CN is officially selected, then the lack of a required key for that language should cause an immediate failure.

It also checks for:

  • Missing keys;
  • Extra keys;
  • Unknown fields;
  • Duplicate fields;
  • Locale metadata;
  • Message types.

In other words, the language catalog itself is part of the release validation.

Currently, the public UI catalog contains a total of 33 keys.


3. The first batch completed was the page framework

The first thing handled was _content/tour/template/index.tmpl.

Including:

  • <html lang>;
  • Browser page titles;
  • The top A Tour of Go;
  • The aria-label for the theme toggle button;
  • Image accessibility text for System / Dark / Light, etc.

After this, running:

Bash
go run -mod=readonly ./cmd/tour-i18n preview \
    --locale zh-CN \
    --id basics/6 \
    --http 127.0.0.1:3999

The Tour service itself actually knows that it is currently running:

Plaintext
zh-CN

Rather than just “replacing a certain .article file with Chinese.”

These are two completely different concepts.


4. Continuing to integrate JavaScript public text into the same catalog

The Tour frontend also has quite a bit of JavaScript text.

The official code itself actually already has a very lightweight i18n outline, so instead of developing a large new frontend internationalization system this time, I reused the existing structure as much as possible.

The Go server injects the required UI messages into:

Plaintext
window.__tourUIMessages

The frontend continues to read them through the existing:

Plaintext
i18n.l(...)

Currently, the integrated items include:

  • Table of contents;
  • Waiting for remote server;
  • Feedback;
  • Feedback Issue title and body templates;
  • Editor control area;
  • Program exit status.

One advantage of this approach is:

The language data still has only one official source, eliminating the need to maintain separate sets of Chinese text in Go, HTML, and JavaScript.


5. The lesson list page was a relatively important part this time

After completing the public UI, /tour/list can now display the actual Chinese module interface.

Currently, the 5 modules are:

  • Using the tour;
  • Basics;
  • Methods and interfaces;
  • Generics;
  • Concurrency.

The module descriptions have also been localized into Chinese.

Figure 1: A Tour of Go Chinese lesson list page, with module titles and descriptions localized
Figure 1: A Tour of Go Chinese lesson list page, with module titles and descriptions localized

A rather noteworthy issue was encountered here.

The module descriptions are not plain text.

The official upstream originally contained structures like:

HTML
<p>...</p>

And:

HTML
<a href="https://go.dev">...</a>

Such rich text structures.

At one point, because HTML tags in the terminal output were “eaten” when displayed in the chat interface, making them look like plain text, I mistakenly thought the upstream module descriptions were originally plain text.

Later, I directly performed a SHA-256 comparison between the frozen source code and the upstream, confirming that the values.js on both sides were exactly identical, and also confirming that the official original text indeed contained <p> and <a>.

Ultimately, the correct design was restored:

Plaintext
module title
→ plain

module description
→ rich

However, the rich here does not allow arbitrary HTML.

Currently, only a very small range of fixed structures is allowed:

  • <p>
  • </p>
  • <a href="https://go.dev">
  • </a>

The presence of unknown tags or unknown attributes will cause a failure.

This preserves the official rich text semantics without turning the UI catalog into an arbitrary HTML injection point.

This experience also demonstrates once again:

When making structural judgments about upstream, do not rely solely on rendered terminal text in a chat window; hashes and direct source code reading are far more reliable.


6. The editor area has finally become truly Chinese as well

Although the lesson content has long been able to display in Chinese, the right-side editor previously still showed:

Plaintext
Syntax
Imports
Reset
Format
Run
Kill

These have now been changed respectively to:

Plaintext
语法高亮
导入
重置
格式化
运行
终止
Figure 2: Chinese lesson page and the localized editor control area
Figure 2: Chinese lesson page and the localized editor control area

This screenshot is also a very important final render from this public UI phase.

It can be seen that:

  • The top now displays “A Tour of Go”;
  • The lesson content on the left is in Chinese;
  • “Imports” and “Syntax” on the right have been localized;
  • “Reset”, “Format”, and “Run” at the bottom display normally;
  • After the Chinese text became longer, there was no obvious compression or misalignment.

However, the screenshot still shows:

Plaintext
off

This is something I specifically decided not to translate.


7. Not modifying everything just to pursue “zero English”

As the public UI localization progressed, a very practical question arose:

If an English word can still be found on the page, must we keep modifying it?

Ultimately, my answer was no.

A read-only audit of the remaining UI was conducted specifically for this, reclassifying the remaining English text based on “user value” and “degree of modification intrusion.”

1. on / off

These two words are not normal HTML text, but are generated by the CSS content: in:

Plaintext
_content/tour/static/css/app.css

If they absolutely had to be localized, it might require further changes to:

  • CSS;
  • DOM;
  • Angular bindings.

And the actual browser result is:

Plaintext
导入 off
语法高亮 off

There is no obvious incongruity.

So the final decision was:

Actively preserve upstream as-is in the first phase.

Not expanding the modification footprint for two very short status words.


8. Not taking over standard library behavior to localize 404 either

Another candidate was:

Plaintext
404 page not found

It comes from the Go standard library’s:

Go
http.NotFound

And it mainly appears for invalid lesson resource requests, which is not part of the normal user navigation process.

Changing this single sentence to Chinese would mean the project starts taking over the standard library’s default 404 response.

The benefit is very low, but the maintenance surface expands.

The final decision was similarly:

Preserve upstream in the first phase.


9. But Program exited was worth handling

In contrast:

Plaintext
Program exited

is different.

This is a very common normal status after running a Go example.

It comes from:

Plaintext
_content/js/playground.js

And whether it is the current standalone SocketTransport or the HTTPTransport that might be used in the future, it will go through this path.

So it falls under:

Plaintext
High-frequency user-visible
+
Low modification intrusion

Ultimately, taking:

Plaintext
Program exited

and integrating it into the existing unified catalog:

Plaintext
execution.exited

The Simplified Chinese displays as:

Plaintext
程序已退出

The entire playground.js only had 1 line of actual status concatenation code modified for this.

There were no modifications to:

  • Transport;
  • WebSocket protocol;
  • Event data format;
  • PlaygroundOutput structure.

This is exactly the kind of localization approach I want to see:

Handle what needs to be handled, but do not refactor upstream just for a single line of UI text.


10. Three HTTPTransport errors are temporarily left unhandled

The current catalog still retains three HTTPTransport-related texts:

Plaintext
Go vet failed.
Go build failed.
Error communicating with remote server.

They currently have no consumer.

This is intentionally retained, not an omission.

Because the current standalone Tour uses SocketTransport by default.

What execution method the final production environment will adopt has not yet been fully determined.

So changing these three now would actually be adding maintenance code for a deployment branch that has not yet been finalized.

The final decision was:

Handle them after the production transport is determined.

If the final zh-CN production site uses HTTPTransport, then these three items will re-enter the to-do list before launch.


11. Also specifically checked the upstream synchronization cost again

There is one issue with public UI localization that I have been quite worried about:

It is easy to modify now, but when upstream upgrades in the future, will large-scale manual merging be needed again?

So a maintenance surface audit was specifically done midway.

Using the commit right before the public UI consumer started:

Plaintext
519cc38

as a baseline, compared against the frozen upstream:

Plaintext
e11dacba76c5aae474746e9eedee19693f492803

Confirming that these upstream-facing files were all identical to the official source code at that time:

Plaintext
_content/tour/template/index.tmpl
_content/tour/static/js/app.js
_content/tour/static/js/controllers.js
_content/tour/static/js/directives.js
_content/tour/static/js/values.js
_content/tour/static/partials/list.html
_content/tour/static/partials/editor.html

The newly added modifications currently still mainly fall under:

  • Text bindings;
  • A small amount of i18n wiring;
  • Data source replacement.

The official UI was not rewritten into a different architecture.

This makes me feel quite relieved.

When synchronizing upstream in the future, the main focus will be on these few consumer files, rather than maintaining a highly divergent Tour frontend.


12. The browser sees the “near-complete product” look for the first time

There was also a small episode during this actual browser acceptance.

When I opened the page for the first time, I found:

  • The top already displayed “A Tour of Go”;
  • But the list modules were still in English;
  • The editor buttons were even just blank buttons.

At first, it looked very much like a code problem.

After a hard refresh, everything immediately returned to normal.

The reason was actually that the browser had cached the old:

Plaintext
/tour/script.js

Resulting in a state where:

Plaintext
New template
+
Old JavaScript

were running mixed.

Using Firefox:

Plaintext
Ctrl + Shift + R

After a hard refresh:

  • Module titles turned into Chinese;
  • Module descriptions turned into Chinese;
  • Editor buttons restored to Chinese;
  • Page layout was normal.

This also served as an early discovery of something to note when accepting the Tour in the future:

After modifying the frontend bundle, if a strange mixed state of old and new UI appears, rule out browser caching first before judging whether it is a program issue.


13. Commits from the public UI phase

This public UI localization ultimately resulted in these commits:

Plaintext
519cc38 feat: 增加公共 UI 多语言目录

5635a86 feat: 接入 Tour 页面框架本地化

234a1c0 feat: 接入 Tour JavaScript UI 本地化

a19c1f5 feat: 接入课程列表与模块本地化

ddf189c feat: 接入编辑器文案并恢复模块富文本语义

42a8b8d feat: 本地化程序退出状态

9ffb5d3 docs: 更新公共 UI 本地化完成状态

The last item also synchronously updated:

Plaintext
docs/PROJECT_STATE.md

The project status is now clearly recorded as:

Plaintext
课程正文
103 / 103 完成
        ↓
课程正文发布前全局质量审计
完成
        ↓
公共 UI 多语言本地化
完成
        ↓
下一阶段
103 页完整 zh-CN 正式发布投影预览
与最终发布验收

14. We cannot just announce “ready for release” yet

Although:

Plaintext
ready=103
pending=0
blocked=0

The lesson content is complete;

The public UI is also complete.

But there is still a very crucial distinction.

During the current development process, it is common to use:

Bash
tour-i18n preview \
    --locale zh-CN \
    --id basics/6

Such a single-page preview.

It only projects the Chinese candidate for the specified page.

So in the screenshots, some English lesson titles can still be seen, such as:

Plaintext
Welcome!
Packages, variables, and functions.
Flow control statements...

These are not public UI translation omissions.

Rather, it is because the other lessons still come from the English upstream.

Before the actual release, the next phase must be completed:

Compose all 103 ready candidates simultaneously into the complete zh-CN Tour.

Then check from a true whole-site perspective:

  • /tour/list;
  • Complete lesson table of contents;
  • All lesson titles and descriptions;
  • 103 lesson pages;
  • Page forward/back navigation;
  • Public UI;
  • Example code;
  • Playground;
  • Page layout;
  • Static resources;
  • Browser console;
  • Locale consistency.

Only after this round passes will what is seen be truly close to the final online version.


15. Going from “translating pages” to “translating a product”

Reaching this point, my understanding of this project has also changed a bit.

At the very beginning, it just looked like:

Translating A Tour of Go into Chinese.

Later, after actually getting hands-on, I realized that translating the lesson content was only one part of it.

A maintainable multilingual Tour also needs to handle:

Plaintext
上游源码同步
        ↓
页面投影
        ↓
整页 AI 翻译
        ↓
结构保护
        ↓
自动校验
        ↓
candidate 状态
        ↓
公共 UI catalog
        ↓
前端 consumer
        ↓
完整站点验收
        ↓
发布

And with every step added, one problem needs to be controlled:

Do not keep expanding the differences with upstream for the sake of theoretical “perfection.”

Retaining on/off, 404, and some execution technical statuses this time is the result of such trade-offs.

They are not translation omissions.

Rather, after evaluation, it was a conscious decision:

This is far enough for the first phase.

Compared to eliminating all marginal English text, I now value more:

  • Complete main flow;
  • Reliable structure;
  • Natural Chinese;
  • Reliable automated validation;
  • Controllable upstream modification surface;
  • The ability to continue maintenance during the next official upgrade.

Currently, both the lesson content and public UI tracks are complete.

Next, we can finally enter the last very important pre-release phase:

103-page complete zh-CN official release projection preview and final release acceptance.

If this round also passes smoothly, then this first phase of the Simplified Chinese A Tour of Go—which started with 103 lesson pages and went through translation architecture, structural restoration, validators, and public UI localization—will truly be not far from an official release.

关于作者 · 持续学习与技术实践

我是一名拥有 15 年以上开发经验的技术从业者,自 2013 年起持续运营个人技术博客,记录工作与个人项目中遇到的真实问题,以及解决问题过程中的探索、实践和思考。

除了技术写作,我也在持续开发和维护自己的独立项目,探索新技术和新工具在实际场景中的应用。我始终相信,没有不值得去解决的问题,也没有不值得去学习的技术。

如果这篇文章对你有所帮助,欢迎浏览博客中的其他文章,也欢迎交流技术经验与想法。

关于我  ·  GitHub  ·  邮件联系