前一阶段，我已经完成了 A Tour of Go 简体中文课程正文的全部翻译，并完成了发布前的全局质量审计。
当前正式发布投影一共是：
ready=103
pending=0
blocked=0
103 个页面全部进入 ready。
不过，课程正文翻译完成，并不等于一个真正可发布的中文版 Tour 已经完成。
实际打开页面后，除了课程正文之外，还有很多属于 Tour 自身的公共界面文案，例如：
- 页面标题；
- 顶部的
A Tour of Go； - 课程列表页标题；
- 模块名称与模块说明；
- 目录；
- 编辑器里的
Syntax、Imports、Run、Format、Reset； - 运行状态；
- 反馈入口；
- 主题切换辅助文案。
如果这些内容仍然保持英文，最终效果就会变成一种“课程是中文、外壳还是英文”的半成品状态。
所以，在 103 个课程页面全部完成以后，我没有马上进入发布，而是单独增加了一个阶段：
公共 UI 本地化。
到今天，这一阶段也终于完成了。
一、课程正文和公共 UI，从一开始就没有放在一起翻译
这个项目早期就确定了一条原则：
课程正文和公共 UI 文案应该分开维护。
课程正文来自官方的 .article 文件，它有自己比较特殊的 present 结构，还涉及：
.play；- 行内代码；
- 链接；
- 静态预格式化代码；
- emphasis；
- 条件 Section；
- directive；
- 页面结构比较。
所以课程正文使用的是“完整课程页面作为最小翻译单元”的工作流。
公共 UI 就完全不同了。
它主要散落在：
_content/tour/template/
_content/tour/static/partials/
_content/tour/static/js/
_content/js/playground.js
internal/tour/
如果把这些 UI 文案继续塞进 .article 翻译系统，反而会把两种完全不同的问题混在一起。
因此，这次给公共 UI 单独建立了：
internal/tour/ui/
├── catalog.go
├── catalog_test.go
├── en.json
└── zh-CN.json
其中：
en.json保存冻结 upstream 对应的英文公共 UI；zh-CN.json保存简体中文公共 UI；catalog.go负责加载和校验；- Go 代码通过
go:embed把语言目录编译进程序。
第一阶段仍然坚持原来的架构方向：
构建时 / 启动时选择单一语言，不做运行时动态语言切换。
这比现在就开发完整语言切换框架简单很多，也更符合当前项目的实际需求。
二、公共 UI 目录不是简单的“找不到中文就显示英文”
这一点我特意做得比较严格。
常见的多语言程序可能会这样处理：
找 zh-CN
→ 找不到
→ fallback 到 en
但对于这个项目来说，我反而不希望这样。
因为 fallback 很容易掩盖问题。
例如未来新增一个 UI 文案，却忘记同步添加中文：
英文 catalog 有
zh-CN catalog 没有
如果自动 fallback，页面仍然可以正常运行，只不过悄悄冒出一句英文。
等真正发布以后才发现，就很难保证完整性。
所以当前采用的是：
不提供英文 fallback。
如果正式选择 zh-CN，那么该语言缺少必要 key 时就应该直接失败。
同时还会检查：
- 缺失 key；
- 多余 key；
- 未知字段；
- 重复字段；
- locale 元数据；
- message 类型。
也就是说，语言目录本身就是发布验证的一部分。
目前公共 UI catalog 一共有 33 个 key。
三、第一批完成的是页面框架
最先处理的是 _content/tour/template/index.tmpl。
包括：
<html lang>；- 浏览器页面标题；
- 顶部
A Tour of Go； - 主题切换按钮的
aria-label； - System / Dark / Light 等图片辅助文字。
这样以后运行：
go run -mod=readonly ./cmd/tour-i18n preview \
--locale zh-CN \
--id basics/6 \
--http 127.0.0.1:3999
Tour 服务本身就真正知道当前运行的是：
zh-CN
而不只是“把某个 .article 文件替换成中文”。
这是两个完全不同的概念。
四、继续把 JavaScript 公共文案接入同一套 catalog
Tour 的前端还有不少 JavaScript 文案。
官方代码本身其实已经存在一个很轻量的 i18n 轮廓，所以这次没有重新开发一套大型前端国际化系统，而是尽量沿用现有结构。
Go 服务端把需要的 UI message 注入：
window.__tourUIMessages
前端继续通过现有的：
i18n.l(...)
读取。
目前已经接入的包括：
- 目录；
- 等待远程服务器；
- feedback；
- feedback 的 Issue 标题和正文模板；
- 编辑器控制区；
- 程序退出状态。
这种方式的一个好处是：
语言数据仍然只有一份正式来源，不需要在 Go、HTML 和 JavaScript 中分别维护一套中文。
五、课程列表页是这次比较重要的一块
完成公共 UI 后，/tour/list 已经可以看到真正的中文模块界面。
目前 5 个模块分别是：
- 使用本教程；
- 基础；
- 方法和接口；
- 泛型；
- 并发。
模块说明也已经完成中文化。
这里还遇到了一个挺值得记录的问题。
模块说明并不是普通纯文本。
官方 upstream 中本来就包含类似：
<p>...</p>
以及：
<a href="https://go.dev">...</a>
这样的富文本结构。
中间有一次，因为终端输出中的 HTML 标签在聊天界面显示时被“吃掉”了，看起来像是普通文本，于是我一度错误地认为 upstream 的模块说明本来就是纯文本。
后来直接对冻结源码和 upstream 做 SHA-256 比较，确认两边的 values.js 完全一致，也确认官方原文确实包含 <p> 和 <a>。
最终重新恢复了正确设计：
module title
→ plain
module description
→ rich
但这里的 rich 并不是允许任意 HTML。
目前只允许极小范围的固定结构：
<p></p><a href="https://go.dev"></a>
出现未知标签或者未知属性都会失败。
这样既保留了官方原本的富文本语义，又不会把 UI catalog 变成一个任意 HTML 注入入口。
这次经历也再次说明：
对 upstream 做结构判断时，不能只依赖聊天窗口里渲染后的终端文本，哈希和直接源码读取要可靠得多。
六、编辑器区域终于也真正变成中文
课程正文虽然早就已经可以显示中文，但右侧编辑器以前还是：
Syntax
Imports
Reset
Format
Run
Kill
现在已经分别变成：
语法高亮
导入
重置
格式化
运行
终止
这张截图也是这次公共 UI 阶段很重要的一张最终效果图。
可以看到：
- 顶部已经显示“Go 语言之旅”；
- 左侧课程正文是中文；
- 右侧“导入”“语法高亮”已经中文化；
- 底部“重置”“格式化”“运行”正常显示；
- 中文文字变长以后没有出现明显挤压或者错位。
不过截图中仍然可以看到：
off
这里是我特意决定不翻译的。
七、没有为了追求“零英文”去修改所有地方
公共 UI 本地化进行到后面，一个很现实的问题出现了：
是不是只要页面上还能找到一个英文词，就必须继续改？
最后我的答案是否定的。
这次专门做了一轮剩余 UI 只读审计，把剩余英文按照“用户价值”和“修改侵入程度”重新分类。
1. on / off
这两个词不是普通 HTML 文本，而是由：
_content/tour/static/css/app.css
中的 CSS content: 生成。
如果一定要中文化，就可能需要进一步改：
- CSS；
- DOM；
- Angular 绑定。
而实际浏览器效果是：
导入 off
语法高亮 off
并没有明显违和。
所以最终决定：
第一阶段主动保留 upstream 原样。
不为了两个很短的状态词扩大修改面。
八、404 也没有为了中文化去接管标准库行为
还有一个候选是：
404 page not found
它来自 Go 标准库的：
http.NotFound
而且主要出现在无效课程资源请求，不属于正常用户导航过程。
如果为了把这一句改成中文，就意味着项目开始自己接管标准库默认 404 响应。
收益很低，维护面却扩大了。
最终同样决定：
第一阶段保留 upstream。
九、但 Program exited 值得处理
相比之下：
Program exited
就不一样了。
这是运行 Go 示例以后很常见的正常状态。
它来自：
_content/js/playground.js
而且无论当前 standalone 的 SocketTransport，还是未来可能使用的 HTTPTransport，都会经过这条路径。
所以它属于：
高频用户可见
+
修改侵入程度较低
最终把：
Program exited
接入现有统一 catalog：
execution.exited
简体中文显示为：
程序已退出
整个 playground.js 为此只修改了 1 行实际状态拼接代码。
没有修改：
- transport；
- WebSocket 协议；
- event 数据格式；
PlaygroundOutput结构。
这正是我希望看到的本地化方式：
该处理的地方处理，但不要因为一句 UI 文案重构 upstream。
十、HTTPTransport 的三条错误暂时不处理
当前 catalog 里还保留了三条 HTTPTransport 相关文案：
Go vet failed.
Go build failed.
Error communicating with remote server.
它们目前没有 consumer。
这是有意保留，而不是遗漏。
因为当前 standalone Tour 默认使用的是 SocketTransport。
正式生产环境最终采用什么执行方式，目前还没有完全确定。
所以现在如果提前改这三条，实际上是在为一个尚未最终确定的 deployment 分支增加维护代码。
最终决定：
等生产 transport 确定以后再处理。
如果最终 zh-CN 生产站使用 HTTPTransport，那么这三项会在上线前重新进入待办。
十一、还特意检查了一遍 upstream 同步成本
公共 UI 本地化有一个我一直比较担心的问题：
现在改得很舒服，以后 upstream 一升级，是不是又得重新大规模手工合并？
所以中途专门做了一次维护面审计。
以公共 UI consumer 开始前的提交：
519cc38
为基准，对照冻结 upstream：
e11dacba76c5aae474746e9eedee19693f492803
确认当时这些 upstream-facing 文件全部与官方源码一致：
_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
当前新增的修改，主要仍然属于：
- 文案绑定；
- 少量 i18n 接线；
- 数据来源替换。
没有把官方 UI 重写成另一套架构。
这让我比较放心。
以后同步 upstream 时，需要重点关注的是这些少量 consumer 文件，而不是维护一个已经高度分叉的 Tour 前端。
十二、浏览器第一次看到“接近完整产品”的样子
这次实际浏览器验收还有一个小插曲。
第一次打开页面时，我发现：
- 顶部已经显示“Go 语言之旅”；
- 但是列表模块还是英文；
- 编辑器按钮甚至只剩空白按钮。
一开始看起来很像代码出了问题。
结果强制刷新以后，马上全部恢复正常。
原因其实是浏览器缓存了旧的：
/tour/script.js
于是出现了：
新模板
+
旧 JavaScript
混合运行的状态。
Firefox 使用：
Ctrl + Shift + R
强制刷新以后：
- 模块标题变成中文；
- 模块说明变成中文；
- 编辑器按钮恢复中文；
- 页面布局正常。
也算是提前发现了以后验收 Tour 时需要注意的一点：
修改前端 bundle 后，如果出现奇怪的新旧 UI 混合状态，先排除浏览器缓存，再判断是不是程序问题。
十三、公共 UI 阶段的几个提交
这次公共 UI 本地化最终形成了这些提交：
519cc38 feat: 增加公共 UI 多语言目录
5635a86 feat: 接入 Tour 页面框架本地化
234a1c0 feat: 接入 Tour JavaScript UI 本地化
a19c1f5 feat: 接入课程列表与模块本地化
ddf189c feat: 接入编辑器文案并恢复模块富文本语义
42a8b8d feat: 本地化程序退出状态
9ffb5d3 docs: 更新公共 UI 本地化完成状态
最后一项同步更新了：
docs/PROJECT_STATE.md
现在项目状态已经明确记录为：
课程正文
103 / 103 完成
↓
课程正文发布前全局质量审计
完成
↓
公共 UI 多语言本地化
完成
↓
下一阶段
103 页完整 zh-CN 正式发布投影预览
与最终发布验收
十四、现在还不能直接宣布“可以发布”
虽然：
ready=103
pending=0
blocked=0
课程正文已经完成；
公共 UI 也已经完成。
但还有一个非常关键的区别。
目前开发过程中经常使用：
tour-i18n preview \
--locale zh-CN \
--id basics/6
这样的单页预览。
它只把指定页面的中文 candidate 投影进去。
所以在截图中还能看到一些英文课程标题，例如：
Welcome!
Packages, variables, and functions.
Flow control statements...
这些并不是公共 UI 漏翻。
而是因为其他课程仍然来自英文 upstream。
真正发布以前，还必须完成下一阶段：
把全部 103 个
readycandidate 同时组成完整 zh-CN Tour。
然后从真正的整站角度检查：
/tour/list；- 完整课程目录；
- 所有课程标题和说明；
- 103 个课程页面；
- 页面前后跳转；
- 公共 UI；
- 示例代码；
- Playground；
- 页面布局；
- 静态资源；
- 浏览器控制台；
- locale 一致性。
只有这一轮通过以后，看到的才是真正接近最终线上版本的效果。
十五、从“翻译页面”走到了“翻译产品”
做到这里，我对这个项目的理解也发生了一点变化。
最开始，它看起来只是：
把 A Tour of Go 翻译成中文。
后来真正动手以后才发现，课程正文翻译只是其中一部分。
一个可以长期维护的多语言 Tour，还需要处理：
上游源码同步
↓
页面投影
↓
整页 AI 翻译
↓
结构保护
↓
自动校验
↓
candidate 状态
↓
公共 UI catalog
↓
前端 consumer
↓
完整站点验收
↓
发布
而且每增加一步，都需要控制一个问题：
不要为了理论上的“完美”不断扩大与 upstream 的差异。
这次保留 on/off、404 和部分执行技术状态，就是这种取舍的结果。
它们不是忘记翻译。
而是经过评估以后，有意识地决定：
第一阶段到这里就够了。
相比把所有边缘英文全部消灭，我现在更看重的是：
- 主流程完整；
- 结构可靠；
- 中文自然；
- 自动校验可靠；
- upstream 修改面可控；
- 下一次官方升级还能继续维护。
目前，课程正文和公共 UI 两条线都已经完成。
接下来终于可以进入最后一个很重要的发布前阶段：
103 页完整 zh-CN 正式发布投影预览与最终发布验收。
如果这一轮也顺利通过，那么这个从 103 个课程页面开始、经历翻译架构、结构恢复、校验器、公共 UI 本地化的 A Tour of Go 简体中文第一阶段，就真的距离正式发布不远了。
A Tour of Go 多语言翻译项目
本系列完整记录 A Tour of Go 多语言翻译项目从架构设计、整页翻译、结构保护、自动校验，到生产发布与后续维护的实际开发过程。
项目入口：
✅ 在线学习：A Tour of Go 简体中文版
✅ 项目源码：GitHub：shuijingwan/go-tour-i18n
当前第一阶段已完成简体中文版本。项目属于非官方社区多语言翻译项目，与 Go 官方无隶属或授权关系。
发表回复