最近，我继续推进 go-tour-i18n 项目的简体中文翻译校准。
上一篇记录中，generics/1 页面连续经历了保护 Token 重复、顺序变化和 legacy present 行内代码边界等问题。这一次，我开始处理新的代表页面：
methods/16 — Type switches
这个页面篇幅不长，却引出了一个此前没有认真确定的问题：
A Tour of Go 左侧课程正文中的代码块，如果包含英文教学注释，这些注释到底应不应该翻译？
右侧编辑器里的 Go 示例代码需要保持官方原样，这一点已经确定。但左侧教程代码块并不完全相同，其中的注释往往就是课程讲解的一部分。
这次最终没有选择“整块代码全部保持英文”，也没有允许模型自由修改整个代码块，而是实现了一套更细粒度的方案：
只允许翻译能够确认是教学说明的注释正文，同时严格保护非注释代码、缩进、注释位置以及注释中的 Go 标识符。
一、第一次翻译：Token 全部正确，结构校验却失败
methods/16 介绍的是 Go 的类型选择。英文原文中包含下面这段代码：
switch v := i.(type) {
case T:
// here v has type T
case S:
// here v has type S
default:
// no match; here v has the same type as i
}
第一次执行 GLM-5.2 翻译时，API 调用正常完成：
- HTTP 状态：
200 - protected token：15 个
- 缺失：无
- 重复：无
- 未知：无
- 顺序错误：无
模型也很自然地翻译了三条注释：
switch v := i.(type) {
case T:
// 这里 v 的类型为 T
case S:
// 这里 v 的类型为 S
default:
// 没有匹配；这里 v 与 i 的类型相同
}
但是，candidate 没有生成。
validator 报告：
protected structure validation failed:
preformatted code mismatch at index 3
expected:
// here v has type T
actual:
// 这里 v 的类型为 T
原因很直接：当时的校验规则要求所有预格式化代码内容逐字一致。即使模型只修改了注释，依然会被视为代码块发生变化。
二、左侧代码注释是否应该翻译
最开始，我考虑过一个最保守的解决办法：
将整个预格式化代码块替换为 protected token，让模型完全看不到代码块内容。
这种方式实现简单，也最安全。模型不可能修改关键字、变量、缩进或注释。
但它也会带来一个明显问题：左侧教程中的重要教学注释会永远保留英文。
methods/16 的三条注释并不是可有可无的补充，它们直接说明了 type switch 各个分支中变量 v 的类型：
- 在
case T中，v的类型为T； - 在
case S中，v的类型为S； - 在
default中，v保持与接口值i相同的接口类型。
对于中文学习者来说，这些注释本身就是课程正文的一部分。
因此，我重新区分了两类代码。
右侧可运行示例
右侧编辑器由 .play 指令加载官方 .go 文件。
第一阶段继续保持：
- Go 代码原样共享；
- 代码注释不翻译；
- 文件名和示例行为与官方一致；
- 不为每种语言维护一份代码副本。
左侧教学代码块
左侧代码块直接嵌入课程正文，其中的自然语言注释可能承担教学作用。
因此更合理的规则是：
- Go 代码本身不能改；
- 说明性注释可以翻译；
- 代码式注释和类型标签保持原样；
- 无法确认用途时，选择不翻译。
三、审计全部 103 个正式页面
在修改实现之前，我先对官方 Tour 的全部正式页面进行了只读审计。
统计范围包括：
- 7 个
.article文件； - 103 个正式页面；
- 使用
golang.org/x/tools/present实际解析 Section； - 只统计解析结果中的
present.Text{Pre:true}； - 使用 Go scanner 识别注释，而不是简单搜索
//。
统计结果如下：
| 项目 | 数量 |
|---|---|
| 正式页面 | 103 |
| 包含预格式化代码块的页面 | 35 |
| 预格式化代码块总数 | 57 |
| 代码块总行数 | 136 |
| 无注释的 Go 代码块 | 44 |
含 // 注释的 Go 代码块 | 13 |
含 /* ... */ 块注释 | 0 |
| 无法安全分类 | 0 |
13 个包含行注释的代码块中，大约 10 个包含值得翻译的自然语言说明。
例如：
byte // alias for uint8
rune // alias for int32
// represents a Unicode code point
这些注释适合翻译为：
byte // uint8 的别名
rune // int32 的别名
// 表示一个 Unicode 码点
还有指针页面中的：
fmt.Println(*p) // read i through the pointer p
*p = 21 // set i through the pointer p
以及 channel 页面中的：
ch <- v // Send v to channel ch.
v := <-ch // Receive from ch, and
// assign value to v.
这些注释都有明确的教学意义。
不过，并不是所有注释都应该翻译。例如：
// int
// float64
// complex128
// OK
// len(a)=5
// len(b)=0, cap(b)=5
这些属于类型名、状态标记或代码式结果。翻译它们没有意义，甚至可能破坏技术含义。
四、最终选择：只翻译已确认的教学注释
经过比较，我最终采用了更细粒度的方案：
对左侧预格式化 Go 代码块进行扫描，只把可确认的自然语言教学注释正文交给模型，其他部分全部保护。
处理流程大致如下：
- 使用 present 解析确定预格式化代码块边界；
- 使用
go/scanner和scanner.ScanComments扫描代码； - 准确识别真正的 Go 注释；
- 排除字符串、原始字符串和 URL 中的
//； - 判断注释是自然语言说明，还是类型名、代码表达式或静态标记；
- 只暴露可以翻译的注释正文；
- 将所有非注释代码、缩进、换行和
//标记替换为 protected token； - 恢复后再由 validator 独立校验。
无法可靠确认的代码块，会退回最保守策略：整块保持原样。
五、为什么不能只保护代码，而忽略注释中的标识符
第一次完成注释级保护以后，methods/16 的代码结构已经不会被模型修改，但仍然存在一个安全缺口。
模型看到的注释正文仍然是：
here v has type T
here v has type S
no match; here v has the same type as i
其中的：
v
i
T
S
都是 Go 代码中的标识符。
虽然第二次翻译中模型恰好保留了它们，但不能依赖模型每次都这样做。模型可能把 v 翻译成“变量”，把 T 改成小写 t，或者漏掉一个标识符。
因此，保护器又增加了一层逻辑：
- 从同一个代码块的非注释代码中收集
token.IDENT； - 在可翻译注释正文中查找这些标识符；
- 每次出现都替换为独立 protected token；
- 只把其余自然语言交给模型。
对于 methods/16，实际保护的标识符序列为：
[v, T]
[v, S]
[v, i]模型实际接收到的内容等价于：
here TOKEN_v has type TOKEN_T
here TOKEN_v has type TOKEN_S
no match; here TOKEN_v has the same type as TOKEN_i
这样，“here”“has type”“no match”等自然语言可以翻译，而 v、i、T、S 必须原样保留。
六、Validator 不依赖 API Token 校验
只在调用 GLM-5.2 时保护标识符还不够。
candidate 后续可能经过人工润色。如果人工误删了注释中的 i，或者把 T 改成了 t，API 阶段的 protected token 校验已经无法提供帮助。
因此，validator 会重新独立检查：
- 注释数量是否一致；
- 注释顺序是否一致；
//所在位置是否一致；- 注释是否仍属于原来的代码行和分支；
- 非注释字节是否逐字一致；
- 注释中的代码标识符数量、大小写和顺序是否一致；
- 可翻译注释是否被改成空内容；
- 不可翻译注释是否保持原样。
也就是说，无论译文来自 GLM-5.2，还是后续人工修改，都必须经过同一套检查。
七、第二次翻译成功通过
完成注释级保护以后，我执行了 methods/16 的第二次开发模式翻译。
结果为：
- HTTP 状态：
200 - prompt tokens：1669
- completion tokens：501
- total tokens：2170
- protected token：19 个
- 缺失：无
- 重复：无
- 未知：无
- 乱序：无
- present 校验：通过
- candidate：成功生成
- 页面状态：
ready
模型生成的三条注释为：
// 此处 v 的类型为 T
// 此处 v 的类型为 S
// 没有匹配；此处 v 与 i 的类型相同
经过人工润色后，最终改为：
// 此时 v 的类型为 T
// 此时 v 的类型为 S
// 没有匹配项；此时 v 的类型与 i 相同
“此时”更适合描述分支内部的变量类型，“没有匹配项”也比“没有匹配”更完整。
八、人工润色又发现了强调结构问题
candidate 生成以后，我对正文进行了人工润色。
英文原文使用：
_type_switch_
在 present 语法中，下划线表示斜体。
正确的中文结构应该是：
_类型选择_
但在一次人工修改中，它被误写成：
*类型选择*
星号在 present 中表示粗体。
当时的 candidate validator 仍然通过。这说明原校验器虽然能够检查行内代码，却没有比较斜体和粗体结构。
于是，本轮又增加了通用的字体结构校验。
现在 validator 会使用 present 自身的解析和样式处理结果，比较：
- 斜体 span 数量；
- 粗体 span 数量；
- program span 数量；
- 各类 span 的类型和顺序；
- span 是否被拆分或合并。
强调范围内的文字可以正常翻译，但结构不能改变。
例如：
_type_switch_
翻译为：
_类型选择_
可以通过。
改成：
*类型选择*
则必须失败。
九、最终译文
经过技术校验和人工润色后，methods/16 的最终内容为：
* 类型选择
_类型选择_ 是一种可以连续执行多个类型断言的语法结构。
类型选择与普通的 switch 语句类似，但类型选择的 case 指定的是类型而不是值；这些类型会与给定接口值中所保存值的类型进行比较。
switch v := i.(type) {
case T:
// 此时 v 的类型为 T
case S:
// 此时 v 的类型为 S
default:
// 没有匹配项；此时 v 的类型与 i 相同
}
类型选择中的声明与类型断言 `i.(T)` 使用相同的语法，
只是将具体类型 `T` 替换为关键字 `type`。
这个 switch 语句会检查接口值 `i`
中保存的值是否为 `T` 或 `S` 类型。
在 `T` 和 `S` 两个 case 中，变量 `v` 的类型分别为
`T` 和 `S`，并保存 `i` 中的值。
在 default 分支中（即没有匹配项时），变量 `v`
的接口类型和值均与 `i` 相同。
.play methods/type-switches.go
十、浏览器预览验证
自动校验通过后，我启动了本地 Tour 预览：
http://127.0.0.1:3999/tour/methods/16
实际检查结果包括：
- HTTP 状态为
200 OK； - 页面标题为“类型选择”；
- 没有残留 GTI18N token；
_类型选择_渲染为<i>，不是<b>；- 三条中文教学注释完整显示；
switch、case、default和type保持原样；v、i、T、S没有变化；- 14 个行内代码均渲染为独立
<code>元素； - 右侧
type-switches.go正常加载。
从实际页面来看，左侧代码块中的中文注释没有影响代码结构，也比保留英文更适合中文学习者。
十一、本轮新增术语
这次还补充了以下 mandatory 术语：
type switch: 类型选择
type switches: 类型选择
type assertion: 类型断言
type assertions: 类型断言
interface value: 接口值
interface type: 接口类型
concrete type: 具体类型
当前 matcher 不自动处理单复数，因此：
type switch
type switches
以及：
type assertion
type assertions
需要分别记录。
switch statement、default case 和 dynamic type 暂时没有加入。前两者可以根据具体句子灵活表达，后者在当前 Tour 中没有实际用例。
十二、最终提交
本轮改动最终提交为：
728adbc feat: 完成 methods/16 并增强代码注释与强调校验
提交统计：
19 files changed, 1186 insertions(+), 26 deletions(-)
提交已经推送到 GitHub 的 main 分支。
提交前完成了：
internal/i18n完整测试；methods/16candidate 校验；git diff --check；- 暂存区检查；
- 浏览器人工预览。
最终工作树干净，本地 main 与 origin/main 保持同步。
十三、当前项目状态
截至 2026 年 8 月 6 日：
- 正式页面：103
- ready：11
- pending：92
- blocked：0
目前完成的代表性校准页面包括：
generics/1flowcontrol/8methods/16
下一页将是：
methods/20
它将继续验证 methods 与 interfaces 章节中的其他特殊结构。
十四、关于 Chrome 网页翻译的对比
我此前学习 A Tour of Go 时，主要依赖 Chrome 的网页翻译功能。
浏览器翻译确实很方便，但面对课程正文、Go 代码、教学注释、编辑器界面和 present 特殊语法时，它很难准确判断哪些内容应该翻译、哪些内容必须保留。
这一次暂时不展开 Chrome 翻译与项目译文的对比。等更多代表性页面完成后，我计划挑选几种不同结构的页面，单独整理一篇实测文章，比较：
- 正文技术含义；
- Go 代码保护；
- 教学注释处理；
- 术语一致性；
- 链接和特殊结构；
- 编辑器界面；
- 长期维护能力。
那篇文章会更适合完整回答一个问题：
专门维护的 A Tour of Go 中文版本，与浏览器即时翻译究竟有什么区别？
结语
methods/16 的第一次失败，并不是因为模型翻译得太差，而是因为项目还没有确定左侧教学代码注释的内容政策。
如果选择整块保护，技术上最简单，但中文课程中的核心教学说明仍会保留英文。
如果允许模型自由翻译整个代码块，又可能修改关键字、标识符、字符串、运算符或缩进。
最终采用的方案位于两者之间：
只翻译能够确认的自然语言教学注释，并对代码、注释结构及注释内标识符进行确定性保护和独立校验。
这次还意外发现了斜体被改成粗体却未被拦截的问题，并进一步补齐了 present 字体结构校验。
从结果来看，代表页校准阶段的价值并不只是多完成几个页面，而是借助每个真实页面逐步确定翻译边界，并把原本依赖人工经验的规则变成可重复执行的程序校验。
需要长期技术维护或远程问题排查？
我是拥有 15+ 年经验的 PHP / Go 后端工程师，长期关注已有系统维护、Bug 修复、性能优化、服务器排查、WordPress 网站维护和小功能迭代。
如果你的项目遇到以下情况，可以先从一次小问题排查开始合作：
- ✅ PHP / Laravel / Yii2 老项目无人维护
- ✅ Go / Gin 后端接口需要排查或优化
- ✅ WordPress 网站访问慢、报错或插件冲突
- ✅ Nginx / MySQL / Redis / Linux 服务器异常
- ✅ CDN / Cloudflare / DNS / HTTPS 配置问题
- ✅ 需要长期远程技术支持或兼职维护
更多介绍请查看：关于我 & 合作
微信：13980074657
邮箱：shuijingwanwq@gmail.com
Telegram：@shuijingwan
GitHub：https://github.com/shuijingwan
发表回复