A Tour of Go 多语言翻译项目实录：完成首个 zh-CN 页面翻译闭环

系列帖子

(1) A Tour of Go 中文版开发实战：英文基线、在线运行与 101 页上游同步体系

(2) 从「A Tour of Go 中文版」这个搜索词开始：我决定做一个持续维护的 Go Tour 中文版

(3) A Tour of Go 中文版项目设计冻结：从 101 页到 103 页，从 Gin 转向 Cobra CLI

(4) A Tour of Go 多语言翻译项目实录：完成首个 zh-CN 页面翻译闭环

2026 年 8 月 2 日，我正式开始推进 go-tour-i18n 项目的简体中文翻译。

今天原本的目标只是翻译第一个页面，但实际推进过程中先后暴露出了页面投影、条件内容、术语一致性、校验规则、重试策略以及 ChatGPT 与 Codex 协作方式等多个问题。

经过一整天的开发和校准，项目最终完成了第一个简体中文页面 welcome/1 的完整翻译闭环，并将经过验证的代码、译文和项目状态提交并推送到了 GitHub。

一、项目当前采用的 upstream 基线

项目继续以官方 Go 网站仓库中的 Tour 源码为基线：

• 官方仓库：golang/website
• 分支：master
• 固定提交：e11dacba76c5aae474746e9eedee19693f492803
• Go 环境：go1.26.0 linux/amd64

当前项目已经确认：

• 共有 7 个 .article 文件；
• standalone 模式下共有 101 个正式课程页面；
• 另外保留 2 个 App Engine 条件页面；
• 共有 92 个 .play 示例引用；
• 共有 1 个 .image 引用。

右侧的 Go 示例代码继续保持官方原样，本阶段只翻译左侧课程正文和后续公共 UI 文案。

二、先解决项目状态如何可靠保存

今天重新开启 ChatGPT 会话后，我发现了一个很现实的问题。

虽然同一个项目此前已经完成了不少工作，但新的聊天未必能够完整恢复上一轮会话的全部细节。如果项目进度主要依靠：

• ChatGPT 记忆；
• Codex 会话记录；
• 已发布的博客文章；
• 人工复制粘贴的执行报告；

那么随着项目逐渐变长，很容易出现上下文遗漏或判断偏差。

今天就曾经因为上下文没有完整恢复，把当天早些时候生成的代码称为“旧模块”，并一度产生了另一套 CLI、页面身份和 upstream 读取逻辑。

经过只读审计后确认，中断任务留下了两套存在重叠的架构：

• 原有 cmd/tour-i18n、internal/i18n、internal/tour；
• 新生成的 cmd/go-tour-i18n、internal/translation、internal/projector 和 internal/upstream。

随后对这些实现进行了整合，最终重新确定：

• 唯一 CLI 为 cmd/tour-i18n；
• 唯一页面身份使用持久 page_id，例如 welcome/1；
• 页面来源为仓库内 _content 和 data/tour-pages.tsv；
• 外部 upstream checkout 只用于同步与核对，不作为翻译运行时依赖；
• internal/i18n.ValidateCandidate 继续作为唯一 candidate 校验入口。

为了让项目状态不再依赖聊天记录，仓库中新增了：

docs/PROJECT_STATE.md

docs/PROJECT_STATE.md

该文档记录当前已经由代码和测试验证的项目状态、已完成能力、当前页面状态以及唯一下一步。

代码和测试仍然是最终事实来源，而 PROJECT_STATE.md 负责把这些事实整理成 ChatGPT、Codex 和我都更容易读取的状态快照。

三、为 GLM-5.2 增加持久、安全的密钥配置

最初执行真实翻译时，Codex 发现：

ZHIPU_API_KEY 未设置

ZHIPU_API_KEY 未设置

如果每次重启 VS Code 都手工输入环境变量，会比较麻烦。

因此，项目增加了本地 .env 自动加载：

go-tour-i18n/
├── .env
└── .env.example

go-tour-i18n/
├── .env
└── .env.example

其中：

• .env 保存本机真实密钥；
• .env.example 只保存变量名称；
• .env 被 /.env 规则明确加入 .gitignore；
• 系统环境变量优先于 .env；
• .env 不会覆盖已经存在的环境变量；
• 密钥不会写入 request、日志或 Git。

本地 .env 权限设置为：

600 .env

600 .env

经过检查，.env 没有出现在 Git 状态和最终提交中。

四、第一次真实翻译暴露了 standalone 页面源错误

首次调用 GLM-5.2 时，模型输出通过了当时的结构校验，并进入了 ready。

但译文中出现了：

#appengine: 远程服务器上的
你电脑上的

#appengine: 远程服务器上的
你电脑上的

调查发现，问题不在模型，而在输入给模型的完整英文页面本身。

请求中实际包含：

to compile and run the program on
#appengine: a remote server.
your computer.

to compile and run the program on
#appengine: a remote server.
your computer.

也就是说，standalone 的 welcome/1 错误保留了 App Engine 条件分支。

根因位于页面拆分逻辑：

• 原实现只识别 #appengine: * 开头的条件页面标题；
• 正文中的 #appengine: a remote server. 没有被排除；
• present 又会把以 # 开头的行视作注释；
• 因此错误 candidate 仍然能够成功解析并通过结构校验。

最终同时修复了两个问题。

第一，standalone 页面源会排除所有 #appengine: 行，同时继续单独保留两个条件页面。

第二，validator 增加防御性规则：

• standalone source 中不得出现 #appengine:；
• standalone candidate 中不得出现 #appengine:。

修复后，welcome/1 的 source hash 更新为：

3fbd64163f0301d60fcf1440c8aa65a79358e7028fec433aee49ae0c364d3034

3fbd64163f0301d60fcf1440c8aa65a79358e7028fec433aee49ae0c364d3034

新的页面源：

• 保留 your computer.；
• 不再包含 #appengine:；
• 不再包含 a remote server.。

旧 source 的运行记录按 source hash 保留，既不会覆盖，也不会占用新 source 的翻译记录。

五、结构正确不代表译文可以直接发布

修复页面源以后，GLM-5.2 很快生成了一份结构正确的译文。

但译文仍存在多项术语问题：

• A Tour of Go 没有翻译；
• previous 和 next 仍保留英文；
• Run、Format 没有翻译；
• slides 被翻译成“幻灯片”；
• tour 的含义出现丢失或机械翻译。

这说明 present 结构、链接 target、.play 和行内代码全部正确，并不代表中文术语已经满足发布标准。

项目随后建立了最小中文术语表：

• A Tour of Go → Go 语言之旅
• previous → 上一页
• next → 下一页
• Run → 运行
• Format → 格式化
• slides → 页面

并将“幻灯片”列为禁用译法。

Validator 也开始根据链接 target 和 label 的结构关系检查术语，而不是简单进行全文字符串匹配。

六、为固定 UI 标签增加确定性术语锁定

开启强制术语校验后，GLM-5.2 连续两次把：

A Tour of Go

A Tour of Go

翻译成：

Go 之旅

Go 之旅

而项目要求的是：

Go 语言之旅

Go 语言之旅

由于请求设置了：

do_sample: false

do_sample: false

相同输入很可能稳定生成相同结果。继续单纯重试只会浪费 Tokens。

这时没有选择在译后进行字符串替换，而是把少量必须严格一致的链接 label 纳入 protected token 流程。

例如：

[[javascript:highlight(".logo")][A Tour of Go]]

[[javascript:highlight(".logo")][A Tour of Go]]

在提交给模型前，链接 target 和显示 label 分别受到保护。

模型完成整页翻译后，label 确定性恢复为：

[[javascript:highlight(".logo")][Go 语言之旅]]

[[javascript:highlight(".logo")][Go 语言之旅]]

当前被锁定的固定 UI 标签包括：

• A Tour of Go
• previous
• next
• Run
• Format

带引号的 "previous" 和 "next" 在恢复中文时仍然保留原有引号。

普通正文没有被大范围锁定，正文仍然交给 GLM-5.2 完整翻译。

七、区分专有名称和普通正文中的 tour

固定标签解决后，下一次译文虽然通过了术语校验，但出现了多处：

本之旅分为……
在本之旅中……
本之旅是交互式的……

本之旅分为……
在本之旅中……
本之旅是交互式的……

问题在于 tour 在不同语境下不能采用同一种译法。

最终明确：

• 专有名称 A Tour of Go → Go 语言之旅
• 普通正文 tour → 教程
• 普通正文 the tour → 本教程

并将以下表达加入禁用译法：

• 本之旅
• 欢迎使用 Go 编程语言之旅
• 幻灯片

固定链接中的 A Tour of Go 继续通过 protected token 恢复为“Go 语言之旅”，普通正文中的 tour 则仍由模型根据提示词翻译。

八、开发阶段取消三次重试限制

最初的正式工作流规定：

完整页面翻译
→ 最多 3 次完整重试
→ 仍失败则 blocked
→ ChatGPT 完整页面兜底

完整页面翻译
→ 最多 3 次完整重试
→ 仍失败则 blocked
→ ChatGPT 完整页面兜底

这个规则适合流程稳定后的正式批量翻译，但今天仍处于开发和校准阶段。

如果开发期间每调整一次 glossary、prompt 或 validator，都继续受三次限制，很快就会把页面送入 blocked，也不利于逐次观察问题。

因此，translate run 增加了开发模式：

go run ./cmd/tour-i18n translate run \
  -id welcome/1 \
  -locale zh-CN \
  -dev

go run ./cmd/tour-i18n translate run \
  -id welcome/1 \
  -locale zh-CN \
  -dev

正式模式仍然：

• 最多执行 3 次完整页面翻译；
• 三次失败后进入 blocked；
• blocked 页面不能继续正式重试。

开发模式则：

• 可以从 pending 或 blocked 继续；
• 每次命令只调用模型一次；
• attempt 编号持续递增；
• 不覆盖旧记录；
• 失败后回到 pending；
• 成功后进入 ready。

这样既能继续开发调试，也能避免一次命令连续消耗多次 GLM Tokens。

九、第六次开发 attempt 最终通过

经过页面源、validator、glossary、protected token 和 prompt 的逐步校准后，attempt-006 最终通过全部校验。

本次调用信息：

• Request ID：2026080221252064d5a523175a438a
• finish_reason：stop
• prompt tokens：1052
• completion tokens：715
• total tokens：1767

最终 candidate 为：

* Hello, 世界

欢迎来到 [[/][Go 编程语言]]之旅。

本教程分为一系列模块，你可以点击页面左上方的
[[javascript:highlight(".logo")][Go 语言之旅]]来访问它们。

你还可以随时点击页面右上方的 [[javascript:highlightAndClick(".nav")][菜单]] 来查看目录。

在本教程中，你将看到一系列页面和练习供你完成。

你可以使用以下方式浏览它们：

- [[javascript:highlight(".prev-page")]["上一页"]] 或 `PageUp` 转到上一页，

- [[javascript:highlight(".next-page")]["下一页"]] 或 `PageDown` 转到下一页。

本教程是交互式的。现在点击
[[javascript:highlightAndClick("#run")][运行]] 按钮
（或按 `Shift` + `Enter`）来编译并运行你电脑上的程序。
结果会显示在代码下方。

这些示例程序展示了 Go 的不同方面。教程中的程序旨在作为你自己实验的起点。

编辑程序并再次运行。

当你点击 [[javascript:highlightAndClick("#format")][格式化]]
（快捷键：`Ctrl` + `Enter`）时，编辑器中的文本会使用
[[/cmd/gofmt/][gofmt]] 工具进行格式化。你可以通过点击
[[javascript:highlightAndClick(".syntax-checkbox")][语法]] 按钮来开启或关闭语法高亮。

当你准备好继续时，点击下方的 [[javascript:highlightAndClick(".next-page")][右箭头]] 或按 `PageDown` 键。

.play welcome/hello.go

* Hello, 世界

欢迎来到 [[/][Go 编程语言]]之旅。

本教程分为一系列模块，你可以点击页面左上方的
[[javascript:highlight(".logo")][Go 语言之旅]]来访问它们。

你还可以随时点击页面右上方的 [[javascript:highlightAndClick(".nav")][菜单]] 来查看目录。

在本教程中，你将看到一系列页面和练习供你完成。

你可以使用以下方式浏览它们：

- [[javascript:highlight(".prev-page")]["上一页"]] 或 `PageUp` 转到上一页，

- [[javascript:highlight(".next-page")]["下一页"]] 或 `PageDown` 转到下一页。

本教程是交互式的。现在点击
[[javascript:highlightAndClick("#run")][运行]] 按钮
（或按 `Shift` + `Enter`）来编译并运行你电脑上的程序。
结果会显示在代码下方。

这些示例程序展示了 Go 的不同方面。教程中的程序旨在作为你自己实验的起点。

编辑程序并再次运行。

当你点击 [[javascript:highlightAndClick("#format")][格式化]]
（快捷键：`Ctrl` + `Enter`）时，编辑器中的文本会使用
[[/cmd/gofmt/][gofmt]] 工具进行格式化。你可以通过点击
[[javascript:highlightAndClick(".syntax-checkbox")][语法]] 按钮来开启或关闭语法高亮。

当你准备好继续时，点击下方的 [[javascript:highlightAndClick(".next-page")][右箭头]] 或按 `PageDown` 键。

.play welcome/hello.go

最终检查结果：

• Go 语言之旅 正确；
• 上一页、下一页 正确；
• 运行、格式化 正确；
• 普通正文使用“教程”和“本教程”；
• 不含“本之旅”；
• 不含“幻灯片”；
• .play welcome/hello.go 保持原样；
• JavaScript target、普通链接 target 和行内代码全部保持一致；
• present 解析和页面结构校验通过。

虽然个别句子未来仍有润色空间，但已经不存在必须退回重译的结构或术语错误。

welcome/1 最终进入：

ready

ready

十、完成首个 zh-CN 页面翻译闭环

最终项目完成了以下闭环：

仓库内完整 Section
→ standalone 页面投影
→ GLM-5.2 整页翻译
→ protected token 恢复
→ present 解析
→ 结构与引用比较
→ glossary 术语检查
→ candidate 落盘
→ ready 状态

仓库内完整 Section
→ standalone 页面投影
→ GLM-5.2 整页翻译
→ protected token 恢复
→ present 解析
→ 结构与引用比较
→ glossary 术语检查
→ candidate 落盘
→ ready 状态

生成的 candidate 位于：

locales/zh-CN/candidates/welcome-1.article

locales/zh-CN/candidates/welcome-1.article

所有 request、response 和 validation 记录均保留下来，作为开发过程的审计依据。

项目完整测试通过，并完成提交：

23b168beb29fbaa99a9b953a41d425558d8f91e6
feat: 完成首个 zh-CN 页面翻译闭环

23b168beb29fbaa99a9b953a41d425558d8f91e6
feat: 完成首个 zh-CN 页面翻译闭环

随后已经推送到 GitHub：

d7f851d..23b168b  main -> main

d7f851d..23b168b  main -> main

最终工作区状态为：

## main...origin/main

## main...origin/main

十一、今天最重要的收获

第一篇页面用了六次开发 attempt，看起来成本并不低。

但前几次失败并不意味着 GLM-5.2 以后会频繁失败，而是在帮助项目发现并解决基础设施问题：

• standalone 页面投影不完整；
• validator 对条件内容缺乏防御；
• 强制 UI 术语不适合完全依赖模型；
• 专有名称和普通词语需要区分语境；
• 开发阶段与正式运行需要采用不同的重试策略；
• 项目状态不能只依赖 ChatGPT 或 Codex 的会话记忆。

这些问题在第一个页面解决后，后续 100 个页面不需要再次承担同样的开发成本。

今天也进一步明确了 ChatGPT、Codex 和我自己的分工：

• ChatGPT 负责架构分析、任务拆分和结果审核；
• Codex 负责直接读取仓库、修改代码和运行测试；
• 我负责监督、成本控制、决策和最终验收。

仓库中的代码、测试、状态文件和 PROJECT_STATE.md，将逐渐成为三者之间更可靠的共同事实来源。

十二、下一步：先评估 DeepSeek 新版本，再决定翻译模型

今天暂时不继续翻译第二个页面。

目前 GLM-5.2 资源包只剩下 300 多万 Tokens。按照现在的购买规则，如果继续补充资源包，需要一次性购买 1 亿 Tokens，并且必须在 3 个月内使用完。

对于仍处于开发和模型评估阶段的 go-tour-i18n 项目来说，现在立即购买这样规模的资源包并不一定合适。

另一方面，DeepSeek 官方更新记录显示，DeepSeek-V4-Flash 已于 2026 年 7 月 31 日进入公开测试；官方文档同时提到，DeepSeek-V4-Pro 计划在 8 月上旬进一步开放支持，但明天仍需根据实际 API 可用情况确认具体模型名称和接入方式。(DeepSeek API Docs)

因此，明天不会直接开始翻译 welcome/2，而是先评估 DeepSeek 新版本在这个项目中的实际表现。

测试时应继续使用今天已经建立的同一套流程：

完整 production 页面
→ protected token
→ 完整页面翻译
→ token 恢复
→ present 解析
→ 结构与引用比较
→ glossary 校验
→ candidate 验证

完整 production 页面
→ protected token
→ 完整页面翻译
→ token 恢复
→ present 解析
→ 结构与引用比较
→ glossary 校验
→ candidate 验证

为了让比较尽可能公平，可以先使用已经熟悉的 welcome/1 作为基准页面，但测试结果应保存到独立的模型评估记录中，不能覆盖当前已经通过验证的 GLM-5.2 candidate。

重点比较：

• protected token 是否能够完整保留；
• present 结构是否能够一次通过；
• 固定 UI 术语是否正确；
• 普通中文正文是否自然；
• 是否会出现机械翻译或擅自改写；
• 首次通过率；
• 输入、输出 Tokens 和实际费用；
• 响应速度与稳定性；
• 相同输入下的结果是否稳定。

如果 DeepSeek 新版本的翻译质量、结构稳定性和成本都可以接受，后续可以考虑将 DeepSeek 作为主要翻译模型，把 GLM-5.2 保留为备用模型或对照模型。

如果测试结果仍然明显不如 GLM-5.2，则继续使用现有剩余 GLM Tokens 完成更有代表性的小规模验证，再根据实际通过率和预计总成本决定是否购买新的资源包。

因此，明天的重点不是追求多翻译几个页面，而是先回答一个对整个项目成本影响很大的问题：

在相同的完整页面输入、结构保护、术语表和自动校验条件下，DeepSeek 新版本能否达到可以正式用于 A Tour of Go 简体中文翻译的质量标准？

确定模型路线以后，再继续第二个页面以及后续小规模页面测试。