A Tour of Go 日语版 ja-JP 正式上线以后，我没有马上开始准备第三门语言。
前一篇已经记录了 ja-JP 第一版最终完成的结果：103 个课程 Page、19 个 eligible Example，共 122 个 TranslationUnit，经过完整的 automatic validation、Quality Check、Final Review、promotion、production 部署和浏览器验收以后，第二门社区语言终于真正运行在生产环境中。
但也正是在完整走完第二门语言以后，一些此前并不明显的问题集中暴露了出来。
这些问题已经不再是“日语翻译得好不好”，而是：
如果现在立即增加第三门语言，我是不是还要重新分析一遍项目架构、开发方式、语言资产、翻译流程、质量审核、构建发布以及生产部署？
如果答案仍然是“需要”，那么项目虽然已经支持多语言，却还没有真正形成一套容易重复执行的多语言扩展流程。
因此，在继续第三门语言之前，我先花了一轮时间，把 ja-JP 上线过程中踩过的坑整理成正式文档。
ja-JP 完成以后，没有马上开始第三门语言
这轮整理最终形成了一个新的提交：
9758458
docs: 建立新增语言标准化流程
这次一共修改了 7 个文档文件，其中最重要的是新增：
docs/NEW_LOCALE_RUNBOOK.md
docs/LOCALE_SURFACE_REVIEW.md同时还调整了：
AGENTS.md
LANGUAGES.md
docs/PRODUCTION_RUNBOOK.md
docs/TRANSLATION_QUALITY_REVIEW.md
docs/TRANSLATION_TERMINOLOGY.md这次没有重新设计已经稳定下来的 TranslationUnit 工作流。
Page 仍然是完整的 present.Section。
Example 仍然是包含允许翻译自然语言注释的完整 Go 示例文件。
Quality Check 仍然逐 TranslationUnit 执行。
Final Review 仍然执行严格的 A-only 门槛。
这次真正要解决的是：
怎样让新增一门语言，从最初的开发准备一直到最终 production，上下游各阶段都能够按照一条已经确定的路径执行，而不是重新探索。
第一个问题：新增语言的全流程仍然太依赖重新分析
ja-JP 完成以后，我最明显的感受之一，是增加一门新语言虽然已经有不少现成能力可以复用，但整个过程仍然存在大量需要临时重新分析和确认的地方。
从最开始准备 ja-JP，到最后正式上线，开发、翻译、质量审核、构建和生产发布几乎每一个阶段，都出现过需要重新判断规则和边界的情况。
例如在开发和语言资产准备阶段，需要重新确认：
- 新 locale 需要增加哪些配置；
locale.json、UI catalog、article metadata 分别承担什么职责；- 首页、课程页、
/tour/list哪些内容属于 TranslationUnit，哪些属于公共 UI； - 新语言是否需要修改模板；
- 哪些 CSS、JavaScript、图片可以跨语言共享；
- 哪些资源必须由每个 locale 独立生成；
- language registry 需要增加哪些信息；
- hostname、SEO identity 和运行时配置应该怎样与 locale 建立关联。
进入翻译阶段以后，又需要确认：
- glossary 应该在什么阶段建立；
- glossary 的适用范围是什么；
- Page 和 Example 怎样进入正式 TranslationUnit workflow；
- UI、首页和 metadata 应该在什么阶段完成本地化；
- automatic validation 与语言质量审核分别负责什么。
到了质量审核阶段，又进一步发现：
- TranslationUnit 全部达到 A，并不等于整个语言站点的全部可见文案都经过了完整审核；
- 公共 UI、首页、
/tour/list、runtime message、article metadata 等非 TranslationUnit 内容也需要正式的语言质量审核； - source ↔ target 的完整语言审核与真实浏览器中的页面验收是两个不同阶段。
随后还需要继续完成：
- promotion；
- projection / preview；
- production bundle；
- 新语言首次生产接入；
- CDN、TLS、DNS；
- Playground Origin；
- SEO；
- 公网和真实浏览器验收。
也就是说，第二门语言虽然最终成功上线，但整个过程中仍然有不少知识依赖上一轮操作经验、聊天上下文和临时分析。
如果第三门语言仍然需要再次经历：
重新理解 locale 架构
→ 重新确认开发与语言资产
→ 重新确认 glossary 和 UI 的边界
→ 重新确认 TranslationUnit workflow
→ 重新确认质量审核范围
→ 重新确认 projection / preview
→ 重新确认 production 接入
→ 最终上线那么项目虽然已经能够支持多个 locale，却还没有真正形成一套可以稳定重复的多语言扩展流程。
因此这次标准化的目标，是把新增语言从开发到正式上线的整个生命周期串起来：
新 locale 决策
→ 开发与语言资产准备
→ glossary
→ UI / metadata
→ TranslationUnit 翻译
→ automatic validation
→ Quality Check / Final Review
→ promotion
→ projection / preview
→ Locale Surface Review
→ publish
→ 首次 production 部署
→ 公网与真实浏览器验收以后开始第三门语言时，希望首先进入这条已经明确的正式路径，而不是再次从项目分析开始。
新增 NEW_LOCALE_RUNBOOK.md
于是这次增加了：
docs/NEW_LOCALE_RUNBOOK.md它被定义为新增一门社区语言的高层入口。
目前新增语言的高层路径已经明确为：
locale / domain / CDN 决策
→ locale glossary
→ locale 配置与公共 UI catalog
→ 首页、导航、语言选择器与 article metadata
→ TranslationUnit 翻译与 automatic validation
→ Candidate Snapshot
→ Quality Check
→ Final Review
→ promotion
→ 完整 projection / preview
→ Locale Surface Review
→ production publish
→ 首次生产基础设施与部署
→ 源站、公网和浏览器上线验收这个文档不会重新实现每一个开发、翻译、审核和部署阶段，而是负责确定完整执行顺序、阶段入口以及各阶段之间的边界。
它也不会重新复制 TranslationUnit 的详细翻译规范。
真正开始 TranslationUnit 翻译以后，仍然进入原来的正式文档：
docs/TRANSLATION_WORKFLOW.md
docs/TRANSLATION_TASK_SPEC.md
docs/RETRANSLATION_RUNBOOK.md
docs/CODEX_TRANSLATION.md新的 Runbook 负责回答的是：
“我要新增一门语言，应该从哪里开始，并按照什么顺序一直做到 production？”
以后开始第三门语言时，不应该再从重新研究整个仓库开始。
第二个问题：TranslationUnit 审得很严格，但公共 UI 没有同等级审核
ja-JP 翻译过程中，TranslationUnit 的质量审核已经相当严格。
当前正式流程中，一个 TranslationUnit 需要经历：
翻译
→ automatic validation
→ Candidate Snapshot
→ ChatGPT Quality Check
→ Final Review
→ promotionQuality Check 要求全部达到 A。
Final Review 同样要求 A 才能 approved。
如果出现 B、C、D，则进入新的 revision batch，而不是把存在语言问题的 candidate 直接发布。
但 ja-JP 做完以后我发现：
课程 TranslationUnit 审得很细，并不意味着整个日语网站的所有文字都已经经过同等级审核。
因为还有一类内容本身就不属于 TranslationUnit。
例如：
- 首页；
- 公共 UI；
/tour/list；- 导航；
- 语言选择器；
- 编辑器按钮；
- Run / Format / Reset；
- runtime message；
- article metadata；
- SEO 可见文案。
这些内容以前会经过结构检查、实际浏览器检查或者开发过程中的人工确认，但没有形成一套和 TranslationUnit Quality Review 明确分离的正式语言质量 gate。
这就是第二门语言真正上线以后暴露出的一个重要缺口。
新增 Locale Surface Review
为此，这次新增：
docs/LOCALE_SURFACE_REVIEW.md而且没有把这些内容强行塞回 TranslationUnit Quality Check。
因为它们本来就是两个不同的问题。
新的 Locale Surface Review 被分成两个阶段。
第一阶段是：
A. Locale-level language quality review这一阶段负责 TranslationUnit 之外可翻译资产的完整语言质量审核。
例如公共 UI 必须同时读取：
internal/tour/ui/en.json
internal/tour/ui/<locale>.json
locales/<locale>/glossary.yaml然后按照 message key 完整进行 source 与 target 比较。
不再只是：
页面打开看看
→ 好像都是日语
→ 没发现明显英文
→ 通过而需要真正检查：
- 是否忠实表达英文 source；
- 是否存在误译；
- 是否存在漏译；
- 技术含义是否准确；
- 是否遵守 glossary；
- 表达是否自然；
- 是否还有不应该保留的英文；
- 是否加入了 source 不存在的解释；
- rich text、变量和链接文字组合后是否仍然正确。
这和 TranslationUnit Quality Review 的原则其实是一致的，只不过审核对象不同。
浏览器验收不能替代语言质量审核
Locale Surface Review 的第二阶段是：
B. Rendered surface acceptance它才负责完整页面组合以后真正呈现在用户面前的结果。
包括：
- 首页；
/tour/；/tour/list；- 导航；
- 语言选择器；
- 编辑器；
- Run / Format / Reset；
- runtime message；
- SEO；
- 桌面端；
- 移动端。
这两个阶段不能互相替代。
也就是说：
source ↔ target 完整语言质量审核
≠
浏览器里看几个页面反过来也一样：
语言文本审核通过
≠
页面实际渲染一定正常一段日语可能翻译得完全正确，但放进按钮以后可能溢出。
一个 UI catalog 可能每一项语言质量都没问题，但在真实页面里可能出现错误的 locale、旧 hostname 或布局问题。
所以以后新增语言时，这两个阶段都要执行。
Surface Review 也开始保留正式 evidence
这次还给 Locale Surface Review 定义了固定审核记录：
data/locale-surface-reviews/<locale>/<review-id>.md它不使用 TranslationUnit 的 A/B/C/D。
最终只使用：
passed
failed并至少记录：
locale
reviewed commit / release
glossary identity
UI / metadata identity
language quality review result
preview acceptance result
production verification result
reviewer
date
decision
issues第一次上线时，在 publish 之前需要完成语言质量审核和 preview acceptance。
真正部署 production 以后，再把公网复核结果写入同一份 evidence。
只有 production 复核也完成以后，才能形成最终：
decision = passed这样以后就不再依赖：
“我记得当时应该已经检查过了。”
第三个问题：首次部署和维护部署以前混得太近
除了开发和质量审核以外，production 阶段同样暴露出了标准化不足的问题。
第二门语言上线过程中，“部署”这个词实际上包含两类完全不同的工作。
第一类是：
第一次给一个新 locale 建立生产环境。
它需要处理：
hostname
CDN
data root
systemd service
loopback port
TLS
Nginx vhost
DNS
Playground Origin
deploy profile
SEO
production acceptance第二类才是以后正常维护时的：
生成新 release
→ deploy
→ health check
→ 完成如果两种场景不明确分开，那么每一次维护部署都很容易重新分析一遍服务器。
固化已经验证过的服务器基线
这次 PRODUCTION_RUNBOOK.md 中专门增加了已经验证过的服务器基线。
包括：
OneinStack
/root/oneinstack
Nginx vhost
/usr/local/nginx/conf/vhost/
SSL
/usr/local/nginx/conf/ssl/
acme.sh
Let's Encrypt + Cloudflare DNS API
应用数据
/data/go-tour[-<locale>]/
进程管理
systemd
service user
go-tour
非中文共享静态资源
https://assets-go-dev.shuijingwanwq.com/这些已经经过 zh-CN 和 ja-JP 的真实生产验证。
所以文档现在明确规定：
除非只读检查发现生产环境真的发生了变化，否则新增 locale 不再重新探测或重新设计整台服务器。
当然，这并不意味着新语言部署时什么都不检查。
新 locale 仍然必须确认：
- hostname 没冲突；
- port 没冲突；
- data root 没冲突；
- service 没冲突；
- DNS 和证书正确；
- Playground Origin 正确。
但这是“确认新 locale 参数”，而不是“重新研究整台服务器”。
首次部署和日常部署正式分开
现在生产流程被明确拆成：
新 Locale 首次生产部署和：
已有 Locale 日常维护部署第一次部署需要完成 production profile 和完整基础设施。
而已经正式上线的 locale，日常 release 更新继续使用：
scripts/deploy-production.sh <release-dir>部署脚本根据 release.json 中的 locale 自动选择正式 profile。
日常维护不应该再次调查 OneinStack、Nginx、acme.sh、systemd 和端口。
这应该能明显降低后续维护成本。
第四个问题：什么叫“术语一致”？
ja-JP 上线以后，我又注意到了一个很有意思的细节。
中文站中：
Go Playground
→ Go 语言演练场而日语站中：
Go Playground
→ Go Playground如果只看页面，很容易产生一个疑问：
为什么一个语言翻译了，另一个语言却没有翻译？是不是标准不统一？
于是我直接检查了两个 locale 的 glossary。
结果发现，中文 glossary 本来就明确规定：
Go Playground: Go 语言演练场日语 glossary 同样明确规定：
Go Playground: Go Playground也就是说，这其实不是随机翻译出来的差异。
两个 locale 都有正式决定。
真正需要统一的，不是：
所有语言必须使用相同的字面结果而应该是：
每个 locale 必须有自己的明确术语决策
+
同一 locale 全站遵守这个决策不同语言当然可以根据自身语言习惯做不同选择。
例如某个名称：
- 中文可能翻译；
- 日语可能保留英文；
- 另一种语言可能采用自己的常用本地化名称。
这些都可以接受。
真正不能接受的是：
同一个 ja-JP 站点里，一处写 Go Playground，另一处临时翻译成另一种日语名称，而 glossary 又没有定义这种差异。
Glossary 不再只约束 TranslationUnit
这也是这轮文档调整以后一个很重要的变化。
过去 glossary 在 TranslationUnit 翻译里已经是正式模型输入。
正式翻译必须同时读取：
manifest.json
manifest 中的全部 inputs/*
locales/<locale>/glossary.yaml但现在进一步明确：
glossary 也是整个 locale 的正式术语权威来源。
不仅 Page 和 Example 要遵守。
这些内容同样需要遵守：
- 公共 UI；
- 首页；
/tour/list；- 导航；
- 编辑器；
- runtime message；
- metadata；
- SEO 可见文案。
当然，glossary 只能决定“一个术语应该怎么处理”。
它不能证明整段翻译一定正确。
所以 Locale Surface Review 中仍然必须做 source ↔ target 比较。
新流程已经接入 AGENTS.md
如果只是写两篇文档，但以后每次还需要手动提醒 Codex 去看，那么“降低重新分析成本”的效果仍然有限。
因此这次还修改了仓库根目录的：
AGENTS.md
现在当任务属于：
新增一门语言
建立新 locale
准备新语言首次上线
评估新 locale 完成度Codex 必须首先读取：
docs/NEW_LOCALE_RUNBOOK.md
docs/LOCALE_SURFACE_REVIEW.md而真正进入 TranslationUnit 翻译时，仍然继续读取：
docs/TRANSLATION_WORKFLOW.md
docs/TRANSLATION_TASK_SPEC.md
docs/RETRANSLATION_RUNBOOK.md
docs/CODEX_TRANSLATION.md
manifest.json
全部 inputs/*
目标 locale glossary.yaml这点很重要。
新的 Runbook 只是高层入口，不会代替 TranslationUnit 的正式翻译规范。
这样以后给 Codex 的指令也不需要越来越长。
不应该每次新增语言，都重新写一套几十条 Prompt，把所有项目规则再人工复制一遍。
更理想的方式应该是：
按仓库正式规范新增 <locale>。然后由 AGENTS.md 自动把任务导航到正确的正式文档。
第二门语言的价值，不只是多了一个日语站
回头看 ja-JP 这一轮，我觉得它最大的价值并不只是最终多出了：
如果只有 zh-CN，我们很容易以为当前架构已经完全支持多语言。
但真正增加第二种语言以后，才发现很多原本隐藏的假设：
- 新 locale 的开发准备仍然需要重新确认；
- UI、metadata、language registry 等语言资产的职责边界不够集中；
- SEO hostname 曾经默认只有中文站；
- Playground Origin 曾经只考虑中文站；
- 新语言部署仍然需要重新分析服务器；
- TranslationUnit Quality Review 没有覆盖所有公共 UI；
- glossary 的全站术语权威边界不够明确；
- “首次上线”和“日常发布”没有完全分离。
这些问题并不是设计文档里想象出来的。
都是第二门语言实际开发、翻译、审核并最终运行以后才暴露出来的。
所以我更愿意把 ja-JP 看成一次真正的多语言扩展验证。
第三门语言应该验证“能不能复制”，而不是继续探索
现在项目已经有：
zh-CN
ja-JP下一门语言真正值得验证的事情已经发生了变化。
过去需要验证：
项目能不能支持第二门语言？现在更应该验证：
按照现有 Runbook，
能不能明显更快、更稳定地增加第三门语言？如果第三门语言开始以后，仍然需要重新分析：
- locale 架构怎么扩展；
- 需要增加哪些开发和语言资产；
- glossary 怎么建立和使用；
- UI 和 metadata 怎么处理；
- TranslationUnit 怎么进入正式 workflow；
- TranslationUnit 之外的语言质量怎么审核；
- projection / preview 怎么验收；
- production 怎么接入；
- Playground 怎么扩展；
- SEO 怎么处理；
那么这次文档整理还不算真正成功。
而如果下一次可以直接按照：
NEW_LOCALE_RUNBOOK
→ 开发与 locale 资产准备
→ TranslationUnit workflow
→ Locale Surface Review
→ first production deployment一路执行下来，那么这个项目才真正开始从“一个不断探索的多语言项目”，转变成：
一套可以重复扩展语言的工程流程。
小结
ja-JP 第一版正式上线以后，我没有马上开始第三门语言，而是先把第二门语言过程中发现的问题固化成项目规范。
这轮最终解决的主要是四件事情：
- 新增语言从开发准备、语言资产、TranslationUnit 翻译、质量审核、projection 到 production 部署，不再依赖重新分析整个项目，而是统一从
NEW_LOCALE_RUNBOOK.md进入标准化流程； - TranslationUnit 之外增加独立的 Locale Surface Review，同时区分完整语言质量审核与真实页面验收；
- production 明确分成新 locale 首次部署和已有 locale 日常维护部署，并固化已经验证的服务器基线；
- glossary 从 TranslationUnit 的正式输入进一步明确为整个 locale 的正式术语权威来源。
与此同时，AGENTS.md 已经把这些规则接入 Codex 的仓库级自动导航。
这意味着下一次开始新语言时，不应该再重新写一套长 Prompt，也不应该重新研究一遍整个项目。
第二门语言解决的是：
能不能真正做出一个新的社区语言站点。
而从第三门语言开始，需要验证的则是：
从开发、翻译、审核到生产上线，这套方法能不能稳定地重复。
这也是我认为多语言项目从“支持多语言”走向“能够持续扩展多语言”之间，真正需要跨过的一步。
A Tour of Go 多语言翻译项目
本系列完整记录 A Tour of Go 多语言翻译项目从架构设计、整页翻译、结构保护、自动校验，到生产发布与后续维护的实际开发过程。
项目入口：
✅ Brazilian Portuguese — Português (Brasil)
✅ Dutch — Nederlands
✅ French — Français
✅ German — Deutsch
✅ Italian — Italiano
✅ Japanese — 日本語
✅ Korean — 한국어
✅ Simplified Chinese — 简体中文
✅ Spanish — Español
✅ Turkish — Türkçe
✅ 项目源码：GitHub：shuijingwan/go-tour-i18n
项目正在持续扩展更多语言版本，并长期维护翻译质量、生产发布与后续更新。项目属于非官方社区多语言翻译项目，与 Go 官方无隶属或授权关系。