Comprehensive Rust 多语言翻译工作流实战指南:基于 Gettext 的 .po 文件本地化体系
Comprehensive Rust 多语言翻译工作流实战指南:基于 Gettext 的 .po 文件本地化体系
Comprehensive Rust 是 Google Android 团队维护的开源 Rust 教学课程,其国际化(i18n)体系基于 GNU Gettext 构建:仓库通过 po/ 目录下的 .po 翻译数据库实现多语言支持,配合 mdbook-xgettext、mdbook-gettext 等插件与自动化 CI 工作流完成抽取、翻译、合并与发布。本文基于仓库根目录的 TRANSLATIONS.md 全文,结合 book.toml、.github/workflows/build.sh、publish.yml 等源码证据,系统讲解如何创建新翻译、刷新过期翻译、本地构建与预览译文,以及翻译如何被自动发布到线上,帮助你在不修改 Markdown 原文的前提下,为课程贡献或维护任意语言的本地化版本。
一、翻译架构总览:为什么选择 Gettext 与 .po 文件
Comprehensive Rust 的多语言支持不采用"复制整套 Markdown 再逐页改写"的笨重方案,而是引入 GNU Gettext 体系。核心设计理念是:译者从不直接修改 src/ 下的 Markdown 文件,所有翻译工作都集中在 po/ 目录下的 .po 文件中。
.po 文件本质上是小型纯文本翻译数据库,其中包含全部英文原文(msgid)以及对应的译文(msgstr)。仓库中每个语言对应一个以 ISO 639 语言代码命名的文件,例如:
- 丹麦语 → po/da.po
- 韩语 → po/ko.po
- 简体中文 → po/zh-CN.po
- 繁体中文 → po/zh-TW.po
当前仓库 po/ 目录下已收录 21 个语言的翻译文件(ar、bn、da、de、el、es、fa、fr、id、it、ja、ko、pl、pt-BR、ro、ru、tr、uk、vi、zh-CN、zh-TW)。这些文件由 messages.pot 模板初始化而来——POT 模板只含英文原文,不含任何译文。
一条典型的 .po 条目形如(取自 po/zh-CN.po 头部):
#: src/SUMMARY.md src/index.md
msgid "Welcome to Comprehensive Rust 🦀"
msgstr "欢迎来到 Comprehensive Rust 🦀"
其中:
#:注释行标注该字符串出现在哪些 Markdown 源文件中(由mdbook-xgettext自动生成);msgid是英文原文,永远不要手动修改;msgstr是该语言对应的译文,是译者唯一的编辑对象。
两个关键原则
- 不要手编
.po文件:原文档明确建议使用 PO 编辑器(如 Poedit 或各类在线编辑器),以确保文件编码正确、转义(如引号")处理无误。 - 编辑后必须运行
dprint fmt:这会统一.po文件的格式(包括msgid/msgstr的换行包裹方式),保证提交到 CI 时不会因为格式问题失败。
在 dprint.json 中可以确认,仓库通过 exec 插件与 prettier 等插件统一驱动格式化;而 CONTRIBUTING.md 则列出格式化工具链:dprint 负责总调度,Rust 用 rustfmt、Python 用 yapf、PO 文件用 msgcat。运行 dprint fmt 即可一键格式化全部文件。
二、构建工具链与前置准备(Preparation)
动手翻译前,需要保证本机可以构建课程,并安装 Gettext 命令行工具。
2.1 安装依赖
在 Linux 上安装 Gettext 工具(msgmerge、msgcat、msginit 等):
sudo apt install gettext
macOS 用户则可用 Homebrew(参见 CONTRIBUTING.md 中的依赖说明):
brew install dprint yapf gettext bazelisk
2.2 构建环境
仓库使用 mdbook 生成课程 HTML,并依赖多个自研/第三方插件(mdbook-course、mdbook-exerciser、mdbook-i18n-helpers、mdbook-pandoc、mdbook-svgbob 等,见 README.md)。
推荐的安装方式是使用 xtask 一键装齐所有固定版本工具(包括 mdbook 0.5.3、i18n-report 0.2.0,以及由 Bazel 构建的 mdbook-gettext、mdbook-xgettext、mdbook-pandoc 等,见 xtask/src/main.rs):
cargo xtask install-tools
装好的工具会出现在 ~/.cargo/bin/ 目录下。随后即可用常规方式构建课程:
mdbook build
2.3 关键配置:book.toml 中的 gettext 管线
book.toml 中与翻译管线相关的配置如下:
[preprocessor.gettext]
after = ["links"]
[output.xgettext]
optional = true
pot-file = "messages.pot"
granularity = 0
[preprocessor.gettext]:注册mdbook-gettext预处理插件,负责在渲染阶段用.po文件把章节内容翻译成目标语言;after = ["links"]指定它在链接预处理之后运行,确保链接等基础结构先行就绪。[output.xgettext]:注册mdbook-xgettext输出插件,负责从 Markdown 源提取英文原文并生成messages.pot模板;optional = true表示该输出是可选的(不强制每次构建都启用);granularity = 0指定抽取的文本粒度(0 表示按整段 Markdown 文本作为一条消息)。pot-file指定生成的模板文件名。[build]下的extra-watch-dirs = ["po", "third_party"]则让mdbook serve能监听po/目录变化并自动重载译文。
此外 book.toml 还内置了 mdbook-pandoc 的 PDF 输出配置(默认 disabled = true,且为主字体配置了 Noto 系列字体与 CJK/Arabic 回退字体,用于正确排版多语言 PDF)。
三、创建与更新翻译(Creating and Updating Translations)
翻译维护遵循一套清晰的操作流程,全部围绕 .pot 模板与 .po 文件展开。
3.1 生成 PO 模板(Generating the PO Template)
要提取全部英文原文并生成 messages.pot,只需构建书籍——构建过程会自动调用 mdbook-xgettext 渲染器:
mdbook build
生成的模板文件位于 book/xgettext/messages.pot。
绝对不要手动触碰这个自动生成的 book/xgettext/messages.pot 文件,也绝不要编辑 po/xx.po 中的 msgid 条目。如果发现原文有误,正确的做法是修改英文 Markdown 源文本;修复会在译者下次执行 msgmerge 时自动流入各 .po 文件。
补充:在 CI 中,build.yml 也使用等价的抽取方式来验证英文源的可提取性——它通过环境变量覆盖
MDBOOK_OUTPUT指定 xgettext 输出后执行mdbook build -d po,再以msgfmt -o /dev/null --statistics po/messages.pot校验模板合法。
3.2 初始化一个新翻译(Initialize a New Translation)
以虚构语言 xx 为例。首先按上文生成 book/xgettext/messages.pot,然后使用 msginit 创建新的 .po 文件:
msginit -i book/xgettext/messages.pot -l xx -o po/xx.po
也可以简单地复制模板再改头部:
cp book/xgettext/messages.pot po/xx.po
如果采用复制方式,需要手动更新文件头部(第一条 msgid "" 所在的消息块)中的语言信息。以现有 po/zh-CN.po 头部为参考,一个合法的文件头应包含:
msgid ""
msgstr ""
"Project-Id-Version: Comprehensive Rust 🦀\n"
"POT-Creation-Date: 2024-04-15T18:42:46+08:00\n"
"PO-Revision-Date: \n"
"Last-Translator: \n"
"Language-Team: Language zh-Hans\n"
"Language: zh_CN\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"
"X-Generator: Poedit 3.4.2\n"
其中 POT-Creation-Date 是后续"回退源文件时间点"的关键依据(详见"发布工作流"一节),Language 字段必须与文件名中的代码一致。
3.2.1 快速机器翻译:cloud-translate
如果希望快速拿到一版初稿,可使用 cloud-translate 工具做机器翻译:
cargo install cloud-translate
未翻译的条目会被发送到 GCP Cloud Translate 处理。需要注意:机器翻译后所有条目都会带有 fuzzy 标记,必须人工逐条复核,因为部分翻译必然有误。
3.2.2 注册新语言标签
初始化新语言后,还需要更新 .github/labeler.yml,为 PR 自动打上语言标签。现有文件已为每个语言配置了如下规则(模式参考):
+"translation/xx":
+ - changed-files:
+ - any-glob-to-any-file: po/xx.po
这样任何修改 po/xx.po 的 PR 都会自动带上 translation/xx 标签,方便维护者按语言分流审阅。
3.3 刷新现有翻译(Refreshing an Existing Translation)
随着课程英文内容持续演进,已有翻译会逐渐过时。判断依据是各 .po 文件头部 POT-Creation-Date 字段——它记录了该翻译上次与英文源同步的时间。
刷新流程分两步:
-
重新抽取英文原文生成模板:
mdbook build -
用
msgmerge把新模板合并进目标语言的.po文件:msgmerge --update po/xx.po book/xgettext/messages.pot
执行后 POT-Creation-Date 会被更新为当前时间,成为翻译新的基线:此后新增的英文文本(包括全新页面)都不会出现在你的翻译里,直到下次再次执行 msgmerge。
msgmerge 对条目的处理规则:
- 未变化的条目保持原样;
- 被删除的条目标记为"旧条目"(保留但不参与输出);
- 发生更新的条目标记为 fuzzy(模糊匹配)。
fuzzy 条目在发布时不会被采用——mdbook-gettext 遇到 fuzzy 条目会回退使用英文原文。因此每次 msgmerge 后都必须人工逐条检查 fuzzy 条目,确认译文正确后移除 fuzzy 标记。
注意(原文档明确要求):提交 PR 时,要么是运行
msgmerge的结果,要么是对该语言.po文件新增翻译工作的结果,不要混在一起提交。两者混合会制造超大 diff,导致 PR 几乎无法审阅。
3.4 编辑翻译(Editing a Translation)
.po 文件虽然是纯文本,但强烈建议使用专用 PO 编辑器。Poedit 是流行的跨平台选择,此外也有众多在线编辑器可选。专用编辑器会自动处理 " 等字符的转义、条目状态的展示(如 fuzzy 显示为 "Needs work")以及文件头管理,显著降低出错概率。
3.5 格式化翻译(Formatting a Translation)
如果 .po 文件格式不正确,PR 会被 CI 拒绝。按前述"前置准备"安装 Gettext 与 dprint 后,运行:
dprint fmt po/xx.po
该命令会自动规范化 .po 文件(包括 msgid/msgstr 的换行包裹)。提交格式化结果并推送分支,PR 即可通过格式检查。
实际上仓库 CI 对 PO 文件格式有多重校验(见 lint.yml,其安装依赖包含 gettext yapf3,并通过 dprint/check 执行格式检查),所以本地先 dprint fmt 能省去来回提交的麻烦。
四、使用翻译:构建与预览本地化版本(Using Translations)
翻译完成后,需要借助 mdbook-gettext 预处理插件把 .po 文件应用到构建输出。核心机制是通过环境变量 MDBOOK_BOOK__LANGUAGE 指定目标语言代码 xx。
重要提示:对标记为 fuzzy 的条目(在 Poedit 中显示为 "Needs work"),
mdbook将使用未经翻译的英文原文。这一行为在使用cloud-translate做初译时尤为关键——因为此时所有条目都会被标记为 fuzzy。
4.1 构建翻译版本(Building a Translation)
确保已至少完成一次构建环境设置后,执行:
MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xx
这会指示 mdbook-gettext 预处理插件使用 po/xx.po 翻译整本书。HTML 输出位于 book/xx/html/。
4.2 实时预览翻译(Serving a Translation)
与常规开发一致,可以使用 mdbook serve 边翻译边预览:
MDBOOK_BOOK__LANGUAGE=xx mdbook serve -d book/xx
当你更新 po/xx.po 文件时,已翻译的书会自动重新加载(得益于 book.toml 中 extra-watch-dirs = ["po", "third_party"] 的监听配置)。
4.3 通过 xtask 便捷构建与预览
除直接使用 mdbook 命令外,README 还提供了 xtask 封装(见 README.md):
# 构建丹麦语翻译版本
cargo xtask build -l da
# 在本地服务器预览丹麦语翻译版本
cargo xtask serve -l da
xx 即 ISO 639 语言代码(如 -l da 对应丹麦语)。
4.4 语言切换器
构建出的多语言 HTML 通过 theme/index.hbs 中内置的 language-toggle 按钮与 language-list 下拉菜单实现站内切换,配合 theme/css/language-picker.css 提供样式支持;对于阿拉伯语等从右向左书写的语言,还有 theme/css/rtl.css 负责 dir="rtl" 布局。这正是 src/running-the-course/translations.md 中"使用右上角语言选择器切换语言"这一体验的落地实现。
五、审阅翻译(Reviewing Translations)
5.1 审阅者与 CODEOWNERS
当一个新翻译启动时,项目会寻找能帮忙审阅的人。审阅者多为 Googler,但并非必须。要想在语言相关新 PR 创建时自动收到邮件,请把自己加入 .github/CODEOWNERS 文件。
5.2 审阅心态与节奏
审阅翻译时请记住:翻译是爱的劳动——有人花自己的空闲时间翻译课程,是想把 Rust 带给使用自己语言的人。因此:
- 新语言的在建 PR 合入后并不会立刻发布,只要翻译合理即可安全合入;
- 与其一次性抛出 50+ 条评论(这会让贡献者不堪重负),不如在后续 PR 中与贡献者逐步改进。
5.3 使用 GitHub Suggestion 功能
审阅翻译 PR 时,优先使用 GitHub 的 suggestion 功能:直接写出你认为某行或某段应该如何措辞(点击工具栏最左侧按钮创建建议)。PR 作者之后可以一键应用全部修改,大幅减少来回沟通的轮次。
5.4 不完整翻译的发布时机
当课程前 1–2 天的内容被翻译完成后,就可以发布该翻译并在翻译页面链接它。这是为了庆祝贡献者的辛勤工作,哪怕翻译并不完整。
六、发布工作流:翻译如何上线(Publication Workflow)
本节面向 Comprehensive Rust 的开发者,但能帮助你理解翻译发布的完整背景。
6.1 从 main 分支到 GitHub Pages
当 main 分支发生变更时,publish.yml CI 工作流随即启动。其 publish 任务执行以下操作:
- 按 CONTRIBUTING.md 安装依赖(包括
gettext工具与全套 mdbook 插件); - 使用 build.sh 构建课程的每一个翻译版本(含英文原版):英文 HTML 输出到
book/html/,语言xx的 HTML 输出到book/xx/html/; - 将整个
book/html/目录发布到 GitHub Pages。
publish.yml 的环境变量 LANGUAGES(见 publish.yml)列出了全部 22 个目标语言(ar bn da de el es fa fr id it ja ko pl pt-BR ro ru tr uk vi zh-CN zh-TW),工作流循环遍历每个语言调用 build.sh,并把各自产物移入 book/html/<lang>/ 子目录。此外,它还会生成两份翻译状态报告(详见下文)。
6.2 build.sh:带额外步骤的 mdbook build
build.sh 同时被 PR 测试工作流 build.yml 与发布工作流 publish.yml 使用。它的核心职责是调用 mdbook build,但额外做了两件事:
-
启用 PDF 输出:通过
export MDBOOK_OUTPUT__PANDOC__DISABLED=false开启mdbook-pandoc。PDF 默认关闭,是为了让普通人无需配置 LaTeX 也能直接mdbook build。构建完成后脚本将 PDF 移入html/目录,并把练习(exerciser)打包成 zip(见 build.sh)。 -
回退源文件到翻译基线(见下文)。
对翻译语言而言,脚本还会:
- 从
po/$book_lang.po文件头提取POT-Creation-Date(build.sh); - 通过环境变量注入语言代码与站点 URL:
export MDBOOK_BOOK__LANGUAGE=$book_lang和export MDBOOK_OUTPUT__HTML__SITE_URL=/comprehensive-rust/$book_lang/; - 对日/韩/简中/繁中等语言加载专属的 Pandoc 配置(
MDBOOK_OUTPUT__PANDOC__PROFILE__PDF__DEFAULTS,见 .github/pandoc/ 目录下的ja.yaml、ko.yaml、zh-CN.yaml、zh-TW.yaml,这些配置为 PDF 指定了对应的 CJK 字体)。
恢复翻译基线(Restoring Translations)
构建翻译版本(非英文)时,build.sh 会把所有 Markdown 文件恢复到 POT-Creation-Date 头部记录的时间点对应的样子。这带来两个后果:
- 翻译不会因为英文文本的后续改动而退化(渲染结果稳定);
- 翻译也不会自动获得英文文本的最新修复(需等译者执行
msgmerge)。
脚本通过一条命令完成恢复(build.sh):
rm -r src/ third_party/
git restore --source "$(git rev-list -n 1 --before "$pot_creation_date" @)" src/ third_party/ book.toml
其中 $pot_creation_date 来自 POT-Creation-Date 头部;git rev-list -n 1 --before 找出该时间点之前的最近一次提交。恢复之后,每个翻译都会使用最新的主题、CSS、JavaScript 等前端资源(因为这些文件不在回退范围内)。
需要注意:build.sh 运行结束后,工作副本处于脏状态(src/、third_party/、book.toml 被回退到了历史版本)。如果想紧接着构建英文版,必须手动清理工作区。
6.3 CI 中的翻译质量门禁
除发布外,build.yml 对每个语言的翻译还设有质量门禁:
- 格式统计校验(非英文语言,build.yml):运行
msgfmt --statistics -o /dev/null "po/${LANGUAGE}.po",若文件语法错误会直接失败; - 代码片段测试:以
MDBOOK_BOOK__LANGUAGE=${{ matrix.language }}环境变量运行mdbook test,验证译文版本中的 Rust 代码片段依然可编译。
另外还有一个专门的 check-msgid-changes.py 检查脚本(由 check-msgid-changes.yml 触发)。它检测"msgid 变了但 POT-Creation-Date 没变"的异常情况:
- 若
msgid变化是msgmerge --update的结果,POT-Creation-Date必然同步更新(时间戳来自模板),脚本会跳过检查; - 若
msgid变化来自手工编辑(比如 PO 编辑器无意间重排了msgid和msgstr的换行),脚本会报错并提示运行dprint fmt归一化格式后重新提交。
该脚本通过 git blame 找出新改动行、再逐行扫描 msgid 与 msgstr 之间的区间来定位非法变更(check-msgid-changes.py),是保证"原文不可篡改"这一铁律落到 CI 层面的实现。
6.4 翻译差异报告(po-diff)
build.yml 中还有一个 po-diff 任务:它会复制当前 PR 分支的 po/ 目录,checkout 基础版本的 po/,然后用 i18n-report diff 命令对比两份目录,把差异摘要写入 GitHub Actions 的步骤总结($GITHUB_STEP_SUMMARY)。这方便审阅者一眼看出某个 PR 对翻译数据做了哪些改动。
七、翻译状态报告(Status Reports)
项目会自动生成两份翻译进度报告:
- 按当前入库状态(Translation status as checked in):反映
po/*.po文件当前入库时的翻译完成度; - 与最新英文源同步后的状态(Translation status after syncing):先用
msgmerge把最新模板合并到所有.po文件,再统计的"潜在完成度"。
你也可以在本地生成报告,查看自己本地改动的效果:
i18n-report translation-report.html po/*.po
i18n-report 工具由仓库的 Bazel 配置声明依赖(见 MODULE.bazel 中的 package = "i18n-report"),cargo xtask install-tools 会安装 0.2.0 版本(xtask/src/main.rs)。
在 publish.yml 中,这两份报告的生成逻辑也清晰可见(publish.yml):
i18n-report report book/html/translation-report.html po/*.po生成"入库状态"报告;- 先把
po/复制为synced-po/,用 xgettext 重建模板并对每个副本执行msgmerge --update,再生成"同步后状态"报告。
八、当前仓库已支持的语言一览
在 src/running-the-course/translations.md 中可以看到当前课程维护的全部翻译状态:
- 已发布翻译:巴西葡萄牙语(pt-BR)、简体中文(zh-CN)、繁体中文(zh-TW)、波斯语(fa)、日语(ja)、韩语(ko)、西班牙语(es)、乌克兰语(uk);
- 进行中翻译:阿拉伯语(ar)、孟加拉语(bn)、法语(fr)、德语(de)、意大利语(it)。
这两份清单与 publish.yml 的 LANGUAGES 环境变量(22 个语言)共同构成了项目的多语言矩阵。读者可使用课程页面右上角的语言选择器在已发布语言间切换,也可以参照本文流程为任何缺失的语言发起全新翻译。
总结
Comprehensive Rust 的翻译体系是一套"原文不可改、译文集中管、CI 全自动"的成熟本地化工程:
- 翻译不碰源码:
src/下 Markdown 永远保持英文,译文全部沉淀在 po/ 目录的.po文件中; - 流程标准化:
mdbook build抽取模板 →msginit建新语言 /msgmerge刷新 → PO 编辑器翻译 →dprint fmt格式化 →MDBOOK_BOOK__LANGUAGE=xx构建预览; - 自动化保障:
build.sh按POT-Creation-Date回退源文件保证翻译稳定性,publish.yml全量构建发布,check-msgid-changes.py与msgfmt --statistics守护msgid不可篡改、文件格式合规。
无论你是想为课程新增一门语言、维护现有翻译,还是仅仅希望用母语阅读这套由 Google Android 团队打造的 Rust 课程,本文给出的完整命令与流程都足以让你独立完成从初始化到上线预览的每一步。