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

A Tour of Go 中文翻译第二批实跑:从 Inline Code 顺序误判到历史响应重新验证

图 2:flowcontrol/6 最终中文页面,return 与 v 为适应自然中文语序发生整体换位

作者:

在

,

Go 学习与文档多语言本地化项目

图3:访问过去的 Go Tour 简体中文站 tour.go-zh.org 时,当前已经无法正常建立连接。

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

本地运行的 A Tour of Go「Methods continued」课程页面,左侧为课程说明,右侧为 Go 代码编辑器及运行结果。

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

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

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

go-tour-i18n 项目完成首个简体中文课程页面 welcome/1 的整页翻译、结构校验和本地预览。

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

图 1:DeepSeek 官方更新日志显示,本次只更新 DeepSeek-V4-Flash,DeepSeek-V4-Pro API 与 APP、Web 模型均未更新

(5) A Tour of Go 中文翻译项目进展:完成前 8 页、修复 present 语法,并暂缓 DeepSeek 对比

图 1:generics/1 简体中文页面本地预览

(6) 一个页面重试五次:使用 GLM-5.2 翻译 A Tour of Go 时遇到的 Token 与 Present 结构问题

图 1:methods/16 简体中文页面浏览器预览

(7) A Tour of Go 中文翻译实录:如何只翻译教学代码注释,而不破坏 Go 代码

图 2:A Tour of Go methods/20「练习:错误」中文候选页面最终渲染效果

(8) A Tour of Go 多语言翻译:当正确的中文语序被受保护标记顺序校验误判

图 3:methods/24 中文页面,静态代码、Bounds 行内代码和链接内的 image.Rectangle 均正确渲染

(9) A Tour of Go 中文翻译完成 7 个代表页校准:最后 3 页又发现了哪些真实问题

图 2:首批 10 个普通页面经过试跑与流程校准后全部进入 ready

(10) A Tour of Go 多语言翻译项目:首批 10 个普通页面试跑,从 2 个 blocked 到全部 ready

图 2:flowcontrol/6 最终中文页面,return 与 v 为适应自然中文语序发生整体换位

(11) A Tour of Go 中文翻译第二批实跑:从 Inline Code 顺序误判到历史响应重新验证

图 1:flowcontrol/6 首次原始输入实验直接通过统一自动校验

(12) A Tour of Go 多语言翻译项目:从 swap 问题重新审视 Token 保护,原始输入与最小保护的一次真实实验

图 7:moretypes/1 最终中文页面预览。左侧课程正文、静态代码块、行内代码和教学注释均正常渲染,右侧官方 Go 示例继续保持原样。

(13) A Tour of Go 多语言翻译实战:第三批 10 页全部 Ready,继续校准 Protected Token 的结构角色

图 4:上游源码确认共有 103 个课程页面,zh-CN 最终达到 ready=103、pending=0、blocked=0

(14) A Tour of Go 多语言翻译项目:zh-CN 103 个课程页面全部 ready,课程正文翻译阶段完成

图 4:GitHub 与 ChatGPT 已成功连接

(15) ChatGPT 连接 GitHub 实测:让 AI 直接读取 go-tour-i18n 仓库参与译文审核

图 3:中文 Go 术语校准完成后,将确定的译法写入 zh-CN glossary

(16) 为什么 channel 最终选择“通道”:A Tour of Go 中文术语统一的一次实践

图 1:技术含义基本正确,但“返回一个返回……”已经明显影响阅读,因此仍被列入 C 类修订

(17) 103 页逐页审核后,只返修 16 页:A Tour of Go 中文正文发布前质量审计

图 2:中文课程页面以及已经完成本地化的编辑器控制区

(18) A Tour of Go 多语言翻译项目:公共 UI 本地化完成,从课程译文走向完整中文界面

图 2:完整 zh-CN 正式投影成功生成,103 个课程页面被重新组装为 7 个 .article

(19) 从 103/103 ready 到完整站点验收:A Tour of Go 中文版补齐正式投影与课程元数据本地化

图 3:从 production bundle 独立启动的 A Tour of Go 简体中文页面,课程正文、公共 UI 和官方 Go 示例均已进入最终发布形态。

(20) A Tour of Go 多语言翻译项目:103 页全部完成后,我终于生成了可独立部署的 zh-CN Production Bundle

图 1:A Tour of Go 简体中文版正式生产页面,远程运行已经成功输出“Hello, 世界”。

(21) A Tour of Go 多语言翻译项目:zh-CN 正式上线,从生产发布到 go.dev Playground 的完整部署记录

图 1:新生产域名 go-dev.shuijingwanwq.com 已正常访问,Go 示例远程运行成功

(22) A Tour of Go 多语言翻译项目:从 go-tour 到 go-dev,完成 EdgeOne、Nginx 与 HTTPS 生产域名迁移

图 1:A Tour of Go 多语言翻译项目正式生产首页

(23) A Tour of Go 多语言翻译项目正式上线:从项目首页、公共 Footer 到生产发布元数据的完整收尾

图 3:GA4 g/collect 请求返回 HTTP 204,并携带当前课程页面地址,确认 Google Analytics 已产生真实事件上报

(24) A Tour of Go 多语言翻译项目:接入 Google Analytics 与百度统计,从 systemd 注入到 EdgeOne 与真实上报验证

图 1:生产环境 robots.txt 与 sitemap.xml 已正确对外提供,Sitemap 共包含 104 个规范 URL。

(25) A Tour of Go 中文站上线后:补齐 robots.txt、Sitemap,并完成五大搜索引擎提交

图 4:发布生产并刷新 EdgeOne 缓存后,再次通过真实手机访问,顶栏项目名称已经完整保持在一行,最终移动端验收通过。

(26) A Tour of Go 多语言翻译项目:修复手机端首页顶栏标题换行,并完成真机验证

图 3:生产自动部署脚本第一次真实运行时,systemd 已经显示 active,但首次 localhost 探测仍然得到 HTTP 000;随后连续 3 次同时满足 active + HTTP 200 后,脚本才判定部署成功,并继续完成公网 HTTP 200 验收。这次真实运行验证了连续应用层健康检查的必要性。

(27) A Tour of Go 多语言翻译项目:从一次 203/EXEC 故障到生产自动部署脚本落地

图 1:阿里云生产环境访问 go.dev Playground 时出现 TLS 握手超时

(28) A Tour of Go 多语言翻译项目:为 Playground 搭建独立的 ZgoCloud 执行代理

图 3:清除 /tour/script.js 缓存后,Run 已直接请求 ZgoCloud /compile 并返回 HTTP 200

(29) A Tour of Go 多语言翻译项目:将生产 Run / Format 切换到 ZgoCloud 执行节点

【图 1:微信中运行 Go 示例时出现 Error communicating with remote server.】

(30) A Tour of Go 中文版手机端运行与格式化偶发失败排查:从间歇性报错到补强 Nginx 可观测性

【图 4:向 golang-dev 公开邮件列表发送 Playground 使用告知邮件并投递成功】

(31) A Tour of Go 多语言项目:为 Playground 代理增加唯一 User-Agent,并主动告知 Go 官方

【图 3:百度剩余 9 个核心 URL 提交成功,remain 归零】

(32) A Tour of Go 搜索引擎收录实测:从 Google 自然索引到百度主动提交与 Bing IndexNow

【图 1:当前正式中文 methods/24 页面,右侧示例代码运行成功】

(33) A Tour of Go 中文翻译完成后,我为什么重新评估 minimal-protect 翻译模式

【图 3:5 个页面 Request SHA256 完全一致,但 Response SHA256 全部不同】

(34) A Tour of Go 翻译实验:更多原始上下文为什么没有更好?从 157 个保护标记到 30 次重复盲评

图 3:3 个代表页 × 4 个评审模型,共 12 次匿名评审的完整排名与第一名票数。

(35) A Tour of Go 翻译质量再评估:minimal-protect 未达预期后,我开始比较 ChatGPT、Codex 与 GLM-5.2

图 2:GitHub 中的 chatgpt-zh-CN-008 重译批次。一个 Batch 同时保存 inputs、raw-responses、candidates、validation 和 retry 记录,GitHub 成为 ChatGPT 与本地翻译流水线之间的数据交接层。

(36) 没有 OpenAI API,我如何用 ChatGPT + GitHub 完成 A Tour of Go 103 页全量重译

图 1:103 个正式课程页面完成最终语义质量审核,结果为 A=103、B/C/D=0,同时不存在缺失、重复或额外页面。A/B/C/D 是本轮项目内部语义质量分级,并不是自动结构 validator 的结果。

(37) 103 页翻完还不能发布:A Tour of Go ChatGPT 译文的语义审核与 Canonical Promotion

图 3:7 个 article endpoint 的 production origin 与 EdgeOne 公网响应全部 exact match,同时新的 ChatGPT 译文标记存在,旧版译文标记已经消失。

(38) 103/103 与 7/7 Exact Match:A Tour of Go ChatGPT 新译文的最终线上验收

【图 2:upstream source preview】

(39) A Tour of Go 多语言翻译项目首次实现 upstream 同步机制:从一次性翻译到长期维护

图 2:A/B/C/D 质量评级规则,展示正式质量 rubric 与 Promotion gate。

(40) A Tour of Go 多语言翻译项目引入 Translation Quality Review:从自动验证到 AI 翻译质量控制

图 4:翻译后 Playground Example,展示中文注释与保持不变的 Go 代码结构。

(41) A Tour of Go 多语言翻译项目实现 Playground Example 本地化:从代码注释翻译到完整学习体验

图 5:公网页面验证广告脚本输出

(42) A Tour of Go 多语言翻译项目接入广告系统:从 AdSense 专用配置到通用 HTML 注入架构

图 3:百度统计单页应用设置

(43) go-dev 单页网站接入统计与 Google AdSense Auto Ads 验证记录

图 1:GitHub 仓库中的多语言翻译项目结构

(44) A Tour of Go 多语言翻译项目:选择日语作为第二语言并启动翻译验证

图 5:模型身份描述不一致

(45) A Tour of Go 多语言翻译项目中的 AI 协作异常排查:一次长期工程会话失效分析

【图 1:ChatGPT GitHub 写入流程调整说明截图】

(46) go-tour-i18n 翻译流程调整:从 ChatGPT GitHub 写入到本地 artifact 导入

图 4 展示了本次异常状态。

(47) go-tour-i18n 翻译自动化流程复盘:已验证的 ChatGPT 翻译能力在新任务中的稳定性问题

【图 6:全部评审结束以后才读取 secret key,完成最终揭盲】

(48) A Tour of Go 翻译质量再评估:Codex High 已接近 ChatGPT High,我决定调整默认翻译引擎

图 4:ja-JP 生产课程页实际运行 Go 示例

(49) A Tour of Go 日语版正式上线:第二门语言 ja-JP 完成生产发布

图 1:ja-JP 上线以后,先提交“新增语言标准化流程”

(50) A Tour of Go 多语言扩展复盘:为第三门语言建立标准化流程

图 1:课程正文结束以后,页面左侧仍然存在大块视觉空白,但 AdSense 并没有在这里插入展示广告。

(51) A Tour of Go 明明有大片空白,为什么 AdSense 就是不显示展示广告?

图 2:golang/website 当前的 _content/tour/。课程内容、静态资源和模板都在这个上游目录中持续维护。

(52) 为了 AdSense,要不要放弃 SPA?A Tour of Go 页面架构的一次取舍

图 4:最终的手动课程广告真实展示在课程内容区域内,而不是 footer 之后。

(53) 保留 SPA 以后,广告应该放在哪里?从 AdSense 预览到方案 B

图 1:Google Search Console 中,多个不同的 A Tour of Go 课程 URL 被判断为“重复网页,用户未选定规范网页”。

(54) SPA 的 SEO 老问题:为什么最后还是给 103 个 A Tour of Go 课程页生成了 Prerender HTML

图 2:方案 B 生产环境中,源码已经正常,但课程主体高度异常缩短,footer 提前进入第一屏。

(55) 从源码空白到 AdSense 高度污染:A Tour of Go 方案 B 的生产收尾

图 1:A Tour of Go 德语版 de-DE 已正式运行在生产环境

(56) A Tour of Go de-DE 上线复盘:第三门语言用了约 16 小时,下一门如何压到 8 小时?

图 1:fr-FR 首次 production 验收完成后,我没有立即开始 ko-KR,而是先连续完成新增语言与首次生产流程的优化

(57) 法语版上线后,我没有马上开始韩语:A Tour of Go 新增语言流程的一轮完善与简化

图 1:根据 ko-KR 期间 76 次 Git 提交估算实际工作时间

(58) 原本预计 6 小时,最后用了约 16~18 小时:A Tour of Go 韩语版上线复盘

图 2:英文 source 与当时发生 validation failure 的 ko-KR candidate 对比

(59) Validator 报错,到底该改译文还是改规则?一次 A Tour of Go 韩语翻译实战

图 2:法语 A Tour of Go 仓库目前已经归档,页面仍保留 553 Commits 和 61 Contributors 的历史

(60) 从法语 553 次提交到韩语两代离线:A Tour of Go 社区翻译为什么难以长期维护

【图 4:es-ES 首次 Production 收口后连续完成的流程优化 commit】

(61) 从 es-ES 首次上线复盘:我把 A Tour of Go 新增语言的 Production 流程又收敛了一轮

图 1:旧公网验收链路连续出现 curl 28 超时,最终导致 public-machine 阶段失败

(62) A Tour of Go Production 公网验收踩坑:从跨境 SOCKS 链路改为 zgocloud direct

图 1:两次 Production Machine Acceptance 都已经通过,但 Headless Chrome 分别在 / 和 /tour/ 判定页面没有完成渲染

(63) 页面明明能打开,为什么 Headless Chrome 仍然判定 Production 失败?

图 3:Bing 从 Google Search Console 中识别到新的 it-IT 站点,并同时发现已有的 1 个 sitemap

(64) GSC → Bing Webmaster Tools:多语言站点如何减少重复验证

图 3:英文站 3 小时内出现 565 个 Cloudflare 来源 URL

(65) IndexNow 实战:手工提交长期不显示,Cloudflare Crawler Hints 却很快出现在 Bing Webmaster Tools

【图 1:A Tour of Go 项目首页目前的语言版本列表】

(66) 从 nl-NL 到 tr-TR:A Tour of Go 连续上线三门语言后,我又优化了哪些流程

【图 4:Go local 页面中已经出现 French、German、Korean、Simplified Chinese】

(67) 从邮件无人回复到进入 Go 官方 Go local:我的 4 个 A Tour of Go 翻译站终于被收录

图8:最终只保留一把启用的新 API Key

(68) 腾讯云 EdgeOne API 自动化:从 CAM 子用户到最小权限 API Key 的完整配置

【图 7:Production Release Batch 最终汇总】

(69) 从同步 Go 官方上游到一个命令发布 10 个语言站:A Tour of Go Production 流程的再次收敛

【图 3:Cloudflare Smart Tiered Cache 已启用】

(70) Cloudflare 缓存 HIT 很快,MISS 却不稳定:回源阿里云杭州的一次真实优化

【图 3:简体中文站 Support 页面】

(71) 广告之外,社区项目如何长期活下去?我给 A Tour of Go 多语言项目加了 Support

图5:评论成功发布

(72) 从 Go Weekly 到 Reddit、DEV 和 Go Forum:第一次系统推广 A Tour of Go 多语言项目

【图 4:RTL 桌面课程布局修复后的效果】

(73) 第一次把 A Tour of Go 做成 RTL:阿拉伯语版本上线,以及我踩过的几个坑

多语言项目应该先做哪些语言?我的 66 个语言版本商业优先级排序

(74) 多语言项目应该先做哪些语言?我的 66 个语言版本商业优先级排序

当术语一致性遇到性能瓶颈:Go 多语言翻译项目的一次架构取舍

(75) 当术语一致性遇到性能瓶颈:Go 多语言翻译项目的一次架构取舍

从 A Tour of Go 走向 Go Learning & Documentation:为什么这个多语言项目需要 v2

(76) 从 A Tour of Go 走向 Go Learning & Documentation:为什么这个多语言项目需要 v2

Markdown 明明可以拆成很多段,为什么 v2 仍然坚持一个 Page 就是一个 TranslationUnit

(77) Markdown 明明可以拆成很多段,为什么 v2 仍然坚持一个 Page 就是一个 TranslationUnit

Tour、Learn、Docs 为什么不应该各维护一份术语表:v2 的统一 Glossary 设计

(78) Tour、Learn、Docs 为什么不应该各维护一份术语表:v2 的统一 Glossary 设计

v2 术语表变更后的页面影响范围判断流程:区分 Compatible 与 Affected,只处理真正受影响的页面。

(79) 术语表改了,为什么不应该让所有页面重新翻译?v2 的影响范围判断

CLI 性能优化示意图:通过 Prepare Once、Reuse Many Times,将执行时间从 6m54.554s 降至 10.335s,约提升 40.1 倍。

(80) 从 6 分 54 秒到 10.3 秒:Go 多语言项目一次 CLI 性能优化实战

Markdown Page 经过 Parse / Protect、Generation 和 Reconstruct / Validate 的流程示意图,强调保护 inline code、链接、代码等机器语义,同时允许译文按照自然语言调整语序。

(81) Markdown 不是纯文本:Learn / Docs 为什么需要新的 parser 与结构保护

历史为什么值得保留:复用已经完成的翻译成果,而不是重新做一遍

(82) 历史为什么值得保留:复用已经完成的翻译成果,而不是重新做一遍

历史状态通过 Trusted Checkpoint 建立可信断点,旧记录继续保留用于审计和诊断,后续工作流从当前状态继续向前,不再要求无限重建过去。

(83) 历史应该被保留,而不是被反复重建:v2 为什么最终需要一个“断点”

v2 依赖与失效传播流程图:从内容变化开始,评估依赖关系和真实影响,将结果区分为“仍然有效”和“需要失效”,只让真正受影响的状态重新进入流程。

(84) 一次内容变化,到底应该让哪些状态失效?v2 的依赖与失效传播设计

v2 本地内容覆盖判断流程图:官方英文页面先检查是否已有正式本地覆盖,有覆盖时使用本地 URL,没有覆盖时直接链接 go.dev,并保持本地路径真实 404。

(85) 有英文页面,不代表一定应该有本地页面:v2 如何处理本地内容覆盖、canonical 与真实 404

v2 代码注释完整性审计流程图:从源页面建立代码块清单,分类教学注释、机器语义和无法判断的内容,再与当前译文精确对应,确认 missing、extra 和 protected mutation 均为 0。

(86) 代码块里的注释为什么不能只靠肉眼检查?v2 如何统计并验证代码注释翻译完整性

结构化语义输入扩展示意图:同一份 books.yaml 原始文件保持不变,旧 parser 识别 10 个可本地化单元,当前 parser 识别 12 个,并新增 PDF 和 GitHub,确认旧单元无删除无修改后重新进入 Generation。

(87) 原始文件一个字没变,为什么还要重新翻译?从 books.yaml 10→12 看语义输入扩展

v2 Activation 流程图:Surface PASS 后先执行只读 activation-preflight 获取 prior_sha256,activation-apply 时通过 CAS 再次比较当前状态,只有 current 等于 prior 才提交 result_sha256,否则停止并重新 preflight。

(88) 审核都通过了,为什么上线前还要再检查一次?v2 的 Activation、prior SHA 与 CAS 设计

v2 分层验证流程图:TranslationUnit、Package Closure 和 Integrated Surface 均通过后进入 Activation,再由 Preview 检查 LoadContent、Compose、Resolver 和 Renderer 的真实运行链;如果实际使用错误 renderer,即使前置内容全部通过,Preview 仍然失败。

(89) Surface 已经 PASS,为什么 Preview 还是会失败?从一次 wrong renderer 看分层验证的价值

更快不一定更好:为什么我主动撤销了一次已经明显变快的性能优化

(90) 更快不一定更好:为什么我主动撤销了一次已经明显变快的性能优化

TranslationUnit 同类问题完整性示意图:左侧 Reviewer 只列出 3 个 examples,Generation 只修这 3 处后仍留下 5 个同类问题,re-QC 再次判 B;右侧 Reviewer 明确 defect category 和 bounded scope,Generation 执行 same-class complete sweep,最终同类残留为 0 并进入 re-QC A。

(91) 为什么修完 Reviewer 指出的所有例子,下一轮还是会失败?从 B→revision→B 看同类问题完整性

immutable source 与 replacement successor 示意图:左侧直接把旧 canonical source A 覆盖成 source B,会使旧 Generation、Review 和 Closure evidence 失去准确对应;右侧保留 source A 作为 immutable predecessor,为新正文建立 source B successor,并重新进入 corpus、glossary review、Generation、QC、closure、Surface 和 Activation 生命周期。

(92) 页面明明是我自己的,为什么不能直接重写?从 /translation/ 改版看 immutable source 与 replacement successor

protected representation 修订能力示意图:左侧 http.Client 被正确保护为 token;中间普通自然语言 Documentation 被错误保护为 opaque token,导致合法 revision 被阻塞;右侧保留旧 representation,通过 representation successor 建立新的可编辑表示,再继续 Generation 和独立 re-QC。

(93) 保护机制也会保护错东西:为什么一个 Documentation 能阻塞整页修订?

一个候选快照原本只应包含 1 个首页翻译单元,却因内容包范围未显式绑定而错误纳入 122 个翻译单元;通过 --content-package site-v2-shell 明确内容包后恢复到正确范围。

(94) 一个候选快照为什么突然多出 122 个单元?从隐式范围到显式内容包契约

Shell 自动化中,当前性检查命令失败并打印 RESULT=FAILED,但由于顶层子 Shell 中错误使用 return,后续命令仍继续执行,最终又打印出错误的 RESULT=PASS。

(95) 命令明明失败了,为什么最后还是 PASS?一次 Shell 自动化的 fail-closed 教训

【图8:Google AI 概览——引用网站的课程目录页】

(96) 同一个 Go 语言之旅网站,Bing、Google 和百度的搜索表现差距有多大?

多个正式命令原本分别重复构建当前内容成员、历史审核链、回执、SHA 和身份标识等可信环境;优化后改为先建立一次已验证的执行环境,再由 current-check、result-pack、import 等连续命令安全复用。

(97) 一个命令快了还不够:为什么我的性能优化开始转向跨命令环境复用

learn-docs-v1 原本以 49 个页面完成了翻译、审核和最终确认,后来发现还缺少 /doc/ 与 /doc/install 两个页面,导致内容包必须从 49 Page 迁移到 51 Page。图片对比了“后期补齐造成迁移成本”和“在 Generation 前先完成成员完整性审计”两种方式。

(98) 只是多了 2 个页面,为什么却触发了一次 49→51 的迁移?

【图2:维护者在 GitHub Issue #1 中回复,说明 math.pi 是官方课程有意设计的教学示例】

(99) 开源项目收到第一个 Issue:为什么我最终选择不修改代码?

一个翻译项目,为什么最后花了大部分时间证明基础设施?

(100) 一个翻译项目,为什么最后花了大部分时间证明基础设施?

【图2:GitHub Secret Scanning 显示 Google API Key 告警】

(101) GitHub 提示 Google API Key 泄露:为什么我最终选择了 Won’t fix?

今天继续推进 go-tour-i18n 项目的简体中文翻译。

在前面的代表页验证和第一批普通页面自动试跑完成之后,翻译、结构保护、自动校验这一整套流程已经逐渐稳定。因此,这次继续选择下一批 10 个普通 pending 页面进行正式翻译。

原本以为这一批应该会比较平稳,实际结果也确实不错:前面大部分页面都顺利进入了 ready。

不过,最后一个 flowcontrol/6 连续 3 次失败,最终进入 blocked。

继续分析以后,却发现一个很有意思的问题:

GLM-5.2 并没有丢失 Protected Token,也没有破坏行内代码。真正出问题的是项目自己的恢复规则。

这个问题最终不仅修复了,还促使项目补上了一项很有价值的新能力:

当保护、恢复或者校验逻辑修复以后,可以直接重新验证之前已经成功返回的模型响应,而不需要再次调用大模型 API。

这次排查过程比较完整,因此单独记录下来。

一、继续第二批 10 个普通页面

当前项目仍然按照“完整课程页面”作为最小翻译单元。

整体流程是:

Plaintext
完整课程页面
→ GLM-5.2 整页翻译
→ 保存 Candidate
→ 自动结构和页面校验
├─ 通过 → ready
└─ 失败 → 有限整页重试 → blocked

这次选择的 10 个页面分别是:

Plaintext
basics/14
basics/15
basics/16
basics/17
flowcontrol/1
flowcontrol/2
flowcontrol/3
flowcontrol/4
flowcontrol/5
flowcontrol/6

正式翻译通过:

Bash
go run -mod=readonly ./cmd/tour-i18n translate run \
    --locale zh-CN \
    --id <page_id>

当前 --id 一次只接受一个页面,因此批量执行时,在外层使用 Shell 循环逐页串行调用。

二、9 页进入 ready,flowcontrol/6 连续 3 次失败

第一轮执行完成以后,结果如下:

页面状态Attempts
basics/14ready1
basics/15ready1
basics/16ready1
basics/17ready1
flowcontrol/1ready1
flowcontrol/2ready1
flowcontrol/3ready3
flowcontrol/4ready1
flowcontrol/5ready1
flowcontrol/6blocked3

其中 flowcontrol/3 虽然使用了 3 次 Attempt,但最终正常进入 ready。

真正需要进一步分析的是 flowcontrol/6。

它在第 3 次正式 Attempt 后仍然失败:

Plaintext
status: blocked
attempts: 3
token_valid: false
present_valid: false

最终错误是:

Plaintext
inline code sentinel 5 opening marker missing
图 1:flowcontrol/6 连续 3 次翻译后因 Inline Code Sentinel 校验失败进入 blocked
图 1:flowcontrol/6 连续 3 次翻译后因 Inline Code Sentinel 校验失败进入 blocked

从这个错误名称来看,很容易首先产生一个判断:

GLM-5.2 是不是把第 5 个 Inline Code Opening Marker 删除了?

但进一步检查原始模型响应以后,发现事实并非如此。

三、flowcontrol/6 本身并没有复杂结构

flowcontrol/6 对应的上游课程页面是:

Plaintext
* If with a short statement

Like `for`, the `if` statement can start with a short statement to execute before the condition.

Variables declared by the statement are only in scope until the end of the `if`.

(Try using `v` in the last `return` statement.)

.play flowcontrol/if-with-a-short-statement.go

这个页面的 Present 结构其实很简单:

  • 普通标题;
  • 普通段落;
  • 5 个行内代码(Inline Code);
  • 1 个 .play Directive。

5 个行内代码依次是:

Plaintext
for
if
if
v
return

真正触发问题的是最后一句:

Plaintext
(Try using `v` in the last `return` statement.)

按照英文源码出现顺序,其中两个行内代码是:

Plaintext
v → return

四、GLM-5.2 根本没有丢 Token

检查 attempt-001、attempt-002 和 attempt-003 后发现,三次模型输出的关键句基本一致。

自然的中文表达是:

(试着在最后一个 return 语句中使用 v。)

于是,两个完整 Inline Code Pair 的出现顺序变成了:

Plaintext
return → v

而英文原文是:

Plaintext
v → return

也就是说,模型做的是:

Plaintext
英文:
v → return

中文:
return → v

最重要的是,模型并没有:

  • 删除 return 的 Opening Marker;
  • 删除 return 的 Closing Marker;
  • 修改 return;
  • 删除 v;
  • 修改 v;
  • 自行增加反引号代码。

两个 Inline Code Pair 都是完整的。

真正发生的仅仅是:

两个完整的 Inline Code Pair 为了适应自然中文语序,整体交换了位置。

五、浏览器中的中文结果反而证明这种换位是合理的

修复并恢复页面后,在浏览器中查看最终中文页面,可以非常直观地看到这句话:

(试着在最后一个 return 语句中使用 v。)

图 2:flowcontrol/6 最终中文页面,return 与 v 为适应自然中文语序发生整体换位
图 2:flowcontrol/6 最终中文页面,return 与 v 为适应自然中文语序发生整体换位

这张截图其实非常能说明问题。

如果仅仅为了保持英文源码中的:

Plaintext
v → return

而强迫中文也使用相同顺序,就很可能需要把中文刻意改写成不自然的表达。

而:

在最后一个 return 语句中使用 v

显然才是正常的中文语序。

因此这次真正需要思考的并不是:

怎么让 GLM 永远不要调整 Token 顺序?

而是:

哪些顺序属于必须保护的结构,哪些顺序应该允许随着目标语言自然变化?

六、真正的问题出在 Restore 的 Source Order 假设

问题最终定位到 validateInlinePairs()。

旧实现按照源码中的 Inline Pair 顺序进行单向扫描。

原始顺序是:

Plaintext
for
→ if
→ if
→ v
→ return

模型输出则是:

Plaintext
for
→ if
→ if
→ return
→ v

旧逻辑按照源码顺序先寻找 v。

找到 v 后,再继续从后面的文本寻找 return。

问题是:

return 已经因为自然中文语序,被完整移动到了 v 前面。

所以程序在 v 后面当然找不到第 5 个 Pair 的 Opening Marker。

最终产生:

Plaintext
inline code sentinel 5 opening marker missing

事实上,这条错误信息也具有一定误导性。

Marker 并没有 Missing。

真正的问题只是:

旧恢复器默认不同 Inline Pair 必须继续维持 Source Order。

七、结构保护不能反过来破坏自然语言

这次最终没有选择继续强化 Prompt,要求 GLM-5.2:

所有 Inline Code Pair 必须严格保持英文原始顺序。

因为这样做虽然可能让旧校验器通过,却会引入另一个问题:

为了程序校验方便,牺牲目标语言自然表达。

这并不符合这个项目最开始确定的翻译目标。

结构保护真正应该严格保证的是:

  • Opening Marker 不能缺失;
  • Closing Marker 不能缺失;
  • Pair 不能被拆散;
  • Pair 内代码内容不能改变;
  • Pair 不能重复;
  • Pair 不能伪造;
  • Pair 不能交叉;
  • Pair 不能嵌套;
  • 模型不能在 Token 外自行增加新的反引号代码。

但是:

两个各自完整、语义独立的 Inline Code Pair,没有必要因为英文出现顺序不同,就禁止它们随目标语言语序整体换位。

八、修改 Inline Pair 恢复规则

因此最终修正的是 Restore,而不是强迫模型改变中文。

新的 validateInlinePairs() 不再按照不同 Pair 的 Source Order 单向扫描。

现在会分别定位每一个 Pair 自己的:

Plaintext
Opening Marker
原始 Payload
Closing Marker

然后严格验证:

  • Opening Marker 必须存在;
  • Closing Marker 必须存在;
  • Opening 必须位于对应的 Closing 前;
  • Pair 内 Payload 必须逐字节一致;
  • Pair 不能交叉;
  • Pair 不能嵌套。

但是允许不同的完整 Pair 整体换位。

因此:

Plaintext
Source:

v → return

转换为:

Plaintext
Translation:

return → v

现在属于合法行为。

前提仍然是两个 Pair 本身都完全没有受到破坏。

九、最终 Validator 原本就允许这种换位

继续审阅以后,还发现一个很重要的问题。

最终的 Candidate Validator 对 Inline Code 原本使用的就是无序保护内容比较。

它严格验证:

  • Inline Code 数量;
  • Inline Code Payload;
  • Inline Code Multiset。

但并不要求不同 Inline Code 始终保持 Source Order。

所以此前实际上存在一个内部规则冲突:

Plaintext
Restore:
要求不同 Inline Pair 保持 Source Order

最终 Validator:
允许完整 Inline Code 根据自然语言整体换位

flowcontrol/6 第一次稳定暴露出了这个矛盾。

修复以后,两层规则终于统一:

单个 Inline Code Pair 内部严格;不同完整 Pair 之间允许自然语序换位。

十、为什么没有修完以后再请求一次 GLM?

Restore 修好以后,又出现了另一个问题。

此时 flowcontrol/6 已经正式进入:

Plaintext
blocked

正式状态下,普通:

Plaintext
translate run

不会继续运行 Blocked 页面。

虽然开发模式可以继续请求模型,但那样会创建新的 Attempt,并再次消耗 GLM Token。

问题是,这次根本没有重新翻译的必要。

因为已经确认:

  • 第 3 次 API 请求成功;
  • finish_reason=stop;
  • 模型 Content 完整;
  • Protected Token 完整;
  • Inline Code 内容没有修改;
  • 真正失败的是旧 Restore。

所以如果修改完项目自己的 Bug,却要求模型重新翻译一次,实际上是在浪费已经获得的有效结果。

更合理的流程应该是:

Plaintext
修复 Restore
→ 读取已经保存的历史模型响应
→ 使用新 Restore 恢复
→ 使用当前 Validator 重新验证

而不是:

Plaintext
修复 Restore
→ 再次调用 GLM

十一、recover-network 不能解决这个问题

项目此前已经存在:

Plaintext
translate recover-network

但是它有非常明确的职责:

恢复真正因为网络故障而失败、实际上没有得到有效模型响应的 Attempt。

它要求历史 Attempt 属于:

Plaintext
api_success=false
network failure
没有有效模型 content

而 flowcontrol/6 完全相反:

Plaintext
api_success=true
有完整 response
有完整 content

失败的只是旧版 Restore。

因此不能为了方便,直接复用 recover-network。

不同类型的失败应该保留明确、独立的恢复语义。

十二、新增 translate revalidate-response

为了解决这类问题,这次新增了一个正式 CLI:

Bash
go run -mod=readonly ./cmd/tour-i18n translate revalidate-response \
    --locale zh-CN \
    --id flowcontrol/6 \
    --attempt 3

它解决的是:

历史模型响应成功,但是因为后来修复了保护、恢复或者校验逻辑,需要按照当前规则重新验证。

整个流程是:

Plaintext
读取历史成功 Response
→ 使用当前 protectTranslation()
→ 使用当前 restore()
→ 使用当前 ValidateCandidate()
→ 全部通过
→ 写入正式 Candidate
→ blocked → ready

整个过程中不会:

  • 调用 GLM;
  • 创建新的 Translation Attempt;
  • 增加 Retry Quota;
  • 修改历史 Response;
  • 修改历史 Request;
  • 覆盖历史 Validation。

十三、Revalidation 仍然必须 Fail Closed

增加历史响应重新验证能力以后,也不能让它变成一个绕过正式状态机的后门。

因此 revalidate-response 会严格检查:

  • Page ID 存在;
  • Locale 有效;
  • 当前 Source Hash 一致;
  • 当前状态必须是 blocked;
  • 指定 Attempt 必须存在;
  • Request、Response、Validation 审计必须完整;
  • 历史 Request 的 Page ID、Locale 和 Source Hash 必须全部匹配;
  • 历史 API 请求必须成功;
  • finish_reason 必须是 stop;
  • Content 不能为空。

之后仍然必须执行完整的:

Plaintext
protect
→ restore
→ ValidateCandidate

只要其中任何一步失败:

Plaintext
status

仍然保持:

Plaintext
blocked

绝不会因为历史 Response 曾经 HTTP 成功,就直接晋升到 ready。

十四、第一次真实历史响应重新验证成功

功能完成并通过测试以后,正式对 flowcontrol/6 的第 3 次历史响应执行:

Bash
go run -mod=readonly ./cmd/tour-i18n translate revalidate-response \
    --locale zh-CN \
    --id flowcontrol/6 \
    --attempt 3

最终结果:

Plaintext
source_attempt: 3
attempts: 3
status: ready

token_valid: true
present_valid: true
passed: true
图 3:复用历史 attempt-003 重新验证成功,flowcontrol/6 从 blocked 恢复为 ready
图 3:复用历史 attempt-003 重新验证成功,flowcontrol/6 从 blocked 恢复为 ready

这张截图中最值得注意的其实不是:

Plaintext
status: ready

而是:

Plaintext
source_attempt: 3
attempts: 3

也就是说,没有出现:

Plaintext
attempt-004

GLM-5.2 也没有再被调用一次。

这从真实数据层面证明:

第 3 次模型输出本身就是可以使用的。此前真正失败的是项目自己的 Restore 规则。

十五、历史 Attempt 不能因为后来成功就被改写

flowcontrol/6 已经存在:

Plaintext
attempt-001
attempt-002
attempt-003

这些历史 Attempt 全部继续保留,而且不会被修改。

重新验证会另外生成:

Plaintext
revalidation-001.json

因此最终审计链表达的是:

Plaintext
attempt-003:
按照当时的 Restore 规则验证失败

↓
修复 Restore

↓
revalidation-001:
使用同一个历史 Response,
按照新的 Restore + Validator 验证成功

而不是把过去的失败记录重新改写成成功。

这对于长期维护非常重要。

失败发生过,就应该保留当时真实的失败记录。

后来的代码修复和重新验证则作为新的审计事件继续追加。

十六、顺便修复审计文件里的绝对路径

第一次产生 revalidation-001.json 后,最终审阅时又发现了一个小问题。

审计数据中的:

Plaintext
response_path
validation_path

最初保存的是本机绝对路径。

例如:

Plaintext
/home/wangqiang/code/go-tour-i18n/...

功能上虽然没有问题,但如果这些数据长期进入 Git 仓库,就会绑定当前机器和当前目录结构。

如果以后:

  • 换电脑;
  • 换用户名;
  • 换仓库目录;

这些绝对路径都会失去可移植性。

因此最终将 Revalidation 审计中的来源路径改为仓库相对路径:

Plaintext
data/translation-runs/zh-CN/flowcontrol/6/sources/.../attempt-003/response.json

并增加测试,确保以后不会再次将本机绝对路径写入这类审计字段。

十七、提交之后,又发现一个已经过时的 TestCommittedStatus

这一批翻译和 Revalidation 功能完成以后,首先创建了提交:

Plaintext
b7de0e0 feat(i18n): 支持历史响应复验并完成第二批页面翻译

但是提交后重新运行:

Bash
go test ./internal/i18n
go test ./...

仍然出现一个失败:

Plaintext
basics/4: ready, attempts=7

一开始看起来像是本次提交导致了某个状态异常。

但是继续分析以后发现:

这个测试在本次提交之前其实就已经失败了。

问题出在 TestCommittedStatus 本身已经跟不上当前项目工作流。

十八、旧 TestCommittedStatus 本质上是一份 Ready 页面白名单

旧测试除了运行基础的 CheckStatus() 外,还维护着一个 Page ID 白名单。

少数已经人工确认的历史页面允许:

Plaintext
ready

而没有进入这个 switch 白名单的页面,默认都被要求:

Plaintext
pending
attempts=0
CandidatePath=""

这种设计在项目早期很合理。

因为当时只有少数代表页面进入 ready,测试可以借此防止没有经过确认的运行期状态意外进入 Git。

但是项目现在已经进入正常批量翻译阶段。

每完成一批页面,就会自然出现新的:

Plaintext
ready

如果仍然沿用旧设计,那么以后每完成 10 页,都得再到测试文件里手工加入 10 个 Page ID。

这显然已经不再合理。

十九、为什么首先只报 basics/4?

目前整个项目已经有不少 ready 页面。

但是测试首先只显示:

Plaintext
basics/4: ready, attempts=7

这并不意味着只有 basics/4 有问题。

只是测试在遇到第一个失败以后就立即 Fatal。

basics/4 恰好是最早遇到的:

没有进入旧白名单,但已经合法成为 ready 的页面。

后面的其他新 Ready 页面实际上也会遇到同样的问题。

二十、attempts=7 并不代表正式允许重试 7 次

basics/4 的另一个特殊点是:

Plaintext
attempts=7

这个数字乍看起来似乎超过了项目正式阶段的有限重试次数。

但这里实际上记录的是:

该页面整个开发历史中单调递增的 Attempt 编号。

basics/4 早期经历过:

  • 基础设施网络失败;
  • Network Recovery;
  • 正式模型响应结构失败;
  • 开发校准阶段继续验证;
  • 最终生成合法 Candidate。

因此历史编号最终来到 7。

它并不等同于:

正式生产流程允许连续自动重试 7 次。

当前 Retry Window 和历史 Attempt 编号实际上已经是两个不同概念。

所以不能为了让测试变绿,就把:

Plaintext
attempts=7

强行改小。

这样反而会破坏真实审计历史。

二十一、把静态白名单改成通用状态不变量

最终没有继续扩大 Ready 页面白名单。

而是将 TestCommittedStatus 改为真正验证“一个已经提交的状态是否合法”。

对于 pending:

  • Candidate Path 必须为空;
  • 不强制要求 attempts=0,以兼容开发阶段已经发生 Attempt、但仍然保持 Pending 的合法情况。

对于 blocked:

  • attempts > 0;
  • Candidate Path 必须为空;
  • 不使用 attempts <= 3 这种错误限制。

对于:

Plaintext
ready
candidate
published

则要求:

  • attempts > 0;
  • Candidate Path 必须是根据 Page ID 推导出来的标准路径;
  • Candidate 文件必须真实存在;
  • Candidate 必须通过当前 ValidateCandidateForLocale()。

于是测试关注的问题变成:

这个状态是否满足状态机长期应该成立的不变量?

而不再是:

这个 Page ID 有没有提前写进测试白名单?

这样以后再增加新的 Ready 页面,就不需要不断修改测试里的 Page ID 列表。

二十二、真正有历史价值的精确断言仍然保留

原来的测试中,一些特殊历史页面还有针对:

  • Attempts;
  • Source Hash;
  • Candidate Path;
  • UpdatedAt;
  • Note;

等字段的精确断言。

这些并没有简单全部删除。

如果某些页面确实承担历史迁移、恢复或者特殊校准行为的回归价值,继续锁定它们的元数据仍然有意义。

最终只是把两种职责拆开:

Plaintext
通用状态合法性

和:

Plaintext
个别重要历史行为回归

不再让一个历史白名单同时承担未来所有页面的状态合法性判断。

二十三、完整测试最终恢复通过

测试调整以后,重新执行:

Bash
go test ./internal/i18n

通过。

随后:

Bash
go test ./cmd/tour-i18n
go test ./...

也全部通过。

状态检查:

Bash
go run -mod=readonly ./cmd/tour-i18n status check \
    --locale zh-CN

结果:

Plaintext
status OK: 103 pages for zh-CN

最后又建立一个独立提交:

Plaintext
13ec759 test(i18n): 修正已提交翻译状态校验

没有将它 Amend 到前一个功能提交中。

所以这次最终产生了两个职责非常清楚的提交:

Plaintext
b7de0e0
feat(i18n): 支持历史响应复验并完成第二批页面翻译

13ec759
test(i18n): 修正已提交翻译状态校验

随后两个提交一起推送到 origin/main。

最终本地和远程均为:

Plaintext
13ec759

工作树保持干净。

二十四、第二批最终结果是 10/10 Ready

刚刚结束自动翻译时,这一批一度是:

Plaintext
9 ready
1 blocked

但经过问题定位和 Restore 修复以后,flowcontrol/6 直接复用了之前的 attempt-003 原始模型响应,并成功重新验证。

所以第二批最终结果实际上是:

Plaintext
10 / 10 ready

截至这次提交完成,整个项目的状态已经来到:

Plaintext
ready=35
pending=68
blocked=0

总页面数:

Plaintext
103

状态检查和完整测试均已通过。

二十五、这次最大的收获并不是又翻译了 10 页

如果只看数字,这次只是新增了 10 个 Ready 页面。

但从工程角度看,我觉得这次更重要的是暴露并解决了三个问题。

第一个是:

Protected Token 的严格保护,不应该等同于严格维持英文语序。

只要一个 Inline Code Pair 本身保持完整,它完全可以随着目标语言的语义单元整体移动。

第二个是:

模型翻译失败与校验器错误拒绝必须严格区分。

如果历史 Response 本身没有问题,只是后来发现旧 Restore 或 Validator 存在缺陷,那么代码修好以后,应当优先复用已有模型响应,而不是重新花一次 API Token。

这也是这次新增:

Plaintext
translate revalidate-response

最大的价值。

第三个是:

测试本身也需要随着项目工作流演进。

项目早期:

Plaintext
只有少量指定页面允许 ready

可能是一条非常有价值的保护规则。

但当项目真正进入批量翻译以后,长期不变量应该变成:

Plaintext
任何 ready 页面,
都必须拥有合法 Candidate,
并通过统一 Validator。

而不是继续维护越来越长的 Page ID 白名单。

二十六、下一步继续小批量推进

目前还有:

Plaintext
pending=68

并且:

Plaintext
blocked=0

接下来仍然不会直接一次把剩余 68 页全部翻译完。

下一步继续采用:

Plaintext
10 页一批

的方式推进。

今天这次经历也再次证明,批量翻译阶段真正需要观察的不只是成功率。

更重要的是:

每一批新的课程页面,会不会出现此前代表页和已有批次没有覆盖到的结构组合?

如果后面继续稳定,再考虑是否扩大每批页面数量。

如果再次出现新的 blocked,则继续按照现在已经逐渐形成的流程处理:

Plaintext
保留完整 Attempt
→ 检查原始模型 Response
→ 判断模型问题还是工具链问题
→ 最小修复
→ 使用统一验证链重新验证

而不是单纯为了让页面通过,不断增加 Prompt 限制或者重复调用模型。

第二批 10 个普通页面,到这里算是正式完成。

相比单纯又增加了 10 个 Ready 页面,我觉得这一批真正留下来的成果其实是两项新的工程能力:

Plaintext
完整 Inline Code Pair 支持自然语序换位

以及:

Plaintext
历史成功模型响应可以重新验证

这两点对于后续剩余 68 页的自动翻译,应该都会比单纯的页面数量更有价值。

Go 学习与文档多语言本地化项目

本系列完整记录 Go 学习与文档多语言本地化项目从 A Tour of Go 起步,逐步扩展到站点首页、项目说明页、学习内容、文档以及未来内容包的实际开发过程,包括架构设计、统一术语治理、整页翻译、结构保护、自动校验、独立质量审核、生产发布与长期维护。

项目源码:
✅ GitHub:shuijingwan/go-tour-i18n

语言版本:

当前跨项目目标语言池共包含 66 个语言版本。Go 项目本身目前提供 65 个社区 Production 语言版本,下面每一门 Go 语言版本都直接链接到其当前公开站点。语言列表沿用项目首页现有的展示顺序。

英语(美国)仅作为跨项目目标语言纳入列表,并不是单独的 Go Production 语言版本。当前 Go 的英文源内容仍为官方 generic English,因此英语(美国)链接到 Go 官方站点,而不是不存在的本地社区部署。

  1. 阿姆哈拉语
  2. 阿拉伯语
  3. 孟加拉语
  4. 葡萄牙语(巴西)
  5. 保加利亚语
  6. 加泰罗尼亚语
  7. 克罗地亚语
  8. 捷克语
  9. 丹麦语
  10. 荷兰语
  11. 英语(美国)(Go 官方英文站点)
  12. 英语(澳大利亚)
  13. 英语(加拿大)
  14. 英语(印度)
  15. 英语(新加坡)
  16. 英语(南非)
  17. 英语(英国)
  18. 爱沙尼亚语
  19. 菲律宾语
  20. 芬兰语
  21. 法语(法国)
  22. 法语(加拿大)
  23. 德语(德国)
  24. 德语(奥地利)
  25. 德语(瑞士)
  26. 希腊语
  27. 古吉拉特语
  28. 希伯来语
  29. 印地语
  30. 匈牙利语
  31. 印度尼西亚语
  32. 意大利语
  33. 日语
  34. 卡纳达语
  35. 哈萨克语
  36. 韩语
  37. 西班牙语(拉丁美洲)
  38. 拉脱维亚语
  39. 立陶宛语
  40. 马来语
  41. 马拉雅拉姆语
  42. 马拉地语
  43. 书面挪威语(Bokmål)
  44. 波斯语
  45. 波兰语
  46. 葡萄牙语(葡萄牙)
  47. 旁遮普语(果鲁穆奇文,印度)
  48. 罗马尼亚语
  49. 俄语
  50. 塞尔维亚语(西里尔文)
  51. 简体中文(中国大陆)
  52. 简体中文(新加坡)
  53. 斯洛伐克语
  54. 斯洛文尼亚语
  55. 西班牙语(西班牙)
  56. 斯瓦希里语(坦桑尼亚)
  57. 瑞典语
  58. 泰米尔语
  59. 泰卢固语
  60. 泰语
  61. 繁体中文(台湾)
  62. 繁体中文(香港)
  63. 土耳其语
  64. 乌克兰语
  65. 乌尔都语
  66. 越南语

项目正在持续扩展新的 Go 学习与文档内容,并长期维护各语言版本的术语一致性、翻译质量、独立审核、生产发布与后续更新。

本项目属于非官方社区多语言本地化项目,与 Go 官方无隶属、授权或背书关系。