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:
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,Resetin 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:
_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:
internal/tour/ui/
├── catalog.go
├── catalog_test.go
├── en.json
└── zh-CN.json
Among these:
en.jsonstores the English public UI corresponding to the frozen upstream;zh-CN.jsonstores the Simplified Chinese public UI;catalog.gohandles 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:
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:
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-labelfor the theme toggle button; - Image accessibility text for System / Dark / Light, etc.
After this, running:
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:
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:
window.__tourUIMessages
The frontend continues to read them through the existing:
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.

A rather noteworthy issue was encountered here.
The module descriptions are not plain text.
The official upstream originally contained structures like:
<p>...</p>
And:
<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:
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:
Syntax
Imports
Reset
Format
Run
Kill
These have now been changed respectively to:
语法高亮
导入
重置
格式化
运行
终止

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:
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:
_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:
导入 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:
404 page not found
It comes from the Go standard library’s:
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:
Program exited
is different.
This is a very common normal status after running a Go example.
It comes from:
_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:
High-frequency user-visible
+
Low modification intrusion
Ultimately, taking:
Program exited
and integrating it into the existing unified catalog:
execution.exited
The Simplified Chinese displays as:
程序已退出
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;
PlaygroundOutputstructure.
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:
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:
519cc38
as a baseline, compared against the frozen upstream:
e11dacba76c5aae474746e9eedee19693f492803
Confirming that these upstream-facing files were all identical to the official source code at that time:
_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:
/tour/script.js
Resulting in a state where:
New template
+
Old JavaScript
were running mixed.
Using Firefox:
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:
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:
docs/PROJECT_STATE.md
The project status is now clearly recorded as:
课程正文
103 / 103 完成
↓
课程正文发布前全局质量审计
完成
↓
公共 UI 多语言本地化
完成
↓
下一阶段
103 页完整 zh-CN 正式发布投影预览
与最终发布验收
14. We cannot just announce “ready for release” yet
Although:
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:
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:
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
readycandidates 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:
上游源码同步
↓
页面投影
↓
整页 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.

