Atlantis 文档多语言流水线实战:基于 Lingo.dev 的机器翻译、链接本地化与完整性校验全解析
Atlantis 文档多语言流水线实战:基于 Lingo.dev 的机器翻译、链接本地化与完整性校验全解析
Atlantis(Terraform Pull Request Automation)的官方站点文档采用「机器翻译 + 维护者人工复核」的方式提供多语言版本,英文是唯一的事实源头,翻译页仅是便利而非权威。本文以仓库根目录的 TRANSLATIONS.md 为核心,结合 .github/workflows/translate-docs.yml、i18n.json、scripts/localize-links.mjs 与 scripts/check-translation-integrity.mjs 等源码,完整剖析这套「按需翻译、逐段增量、链接兜底、可执行内容零改动」的文档国际化流水线。读完本文,你将掌握 Atlantis 站点翻译的触发机制、Lingo.dev 配置、增量翻译的锁文件原理、半翻译 locale 的链接降级策略、完整性校验的八个检查维度,以及本地复现与新增语言的具体操作步骤。
一、背景:为什么文档需要机器翻译
Atlantis 的文档规模庞大,涵盖 docs、guide、blog、contributing 四个目录及站点顶层页面。逐条人工翻译不现实,因此项目选择了机器翻译 + 人工审查的混合模式,并明确立下两条原则:
- 英文是事实源头(source of truth):翻译页只是便利性副本,永远不构成权威;
- 翻译页必须保持"可执行内容"与英文一致:命令、代码块、链接目标等一旦被改动,比整页不翻译对读者的伤害更大。
这与服务端本身的国际化策略完全对齐:Atlantis 服务端通过 --language 参数支持界面语言,当前支持英语(en)与西班牙语(es)两种,见 server/i18n/i18n.go 中 SupportedLanguages() 的实现与 server/user_config.go 中 Language / LanguageConfigFile 两个配置项;对应翻译文案位于 server/i18n/locales/en.yaml 与 server/i18n/locales/es.yaml。文档站目前也只翻译了 西班牙语(es),与服务端语言保持同构。
从源码结构看,这一设计是有意为之:让文档站点与服务器进程的语言集合保持一致,避免出现"服务端支持而文档没有翻译,或文档翻译了但服务端不认"的错位。
二、整体工作流:一次翻译从触发到合并的全过程
翻译由 GitHub Actions 工作流 .github/workflows/translate-docs.yml 驱动,触发条件是 main 分支上英文文档发生变化,具体触发路径包括:
runatlantis.io/docs/**/*.md、guide/**/*.md、blog/**/*.md、contributing/**/*.mdrunatlantis.io/*.md(站点顶层页面)i18n.json、scripts/localize-links.mjs、scripts/check-translation-integrity.mjs、scripts/align-tables.mjs、工作流自身
同时支持 workflow_dispatch 手动触发,并带有一个 force 布尔输入:置为 true 时忽略 i18n.lock 的校验和,强制全量重译。
整个流水线按如下五步推进:
- 暂存英文源(Staging):把
runatlantis.io下待翻译目录里的 Markdown 文件用rsync复制到临时目录.lingo-src/en/,只保留*.md(图片、Terraform 示例等资产不复制)。Lingo.dev 通过把[locale]占位符替换成源语言来定位文件,暂存拷贝让真实英文树保持在原地不动。同时,分支上已有的翻译也会被复制到.lingo-src/<locale>/——否则每次运行都会因为没有目标文件而全量重译,浪费 token 预算并重写未变化的页面。 - 执行翻译:运行 Lingo.dev(Apache-2.0 协议,版本固定为
lingo.dev@0.138.4),配置来自 i18n.json。它把 Markdown 解析成 AST 并跳过代码节点,因此围栏代码块和行内代码永远不会被送去翻译。i18n.lock 按内容片段记录校验和,某段英文改动了,只有该段会被重新翻译。 - 回写结果:把
.lingo-src/<locale>/的内容同步到runatlantis.io/<locale>/(用rsync --delete --exclude='images/',翻译目录自身不带 images 子目录)。 - 链接本地化与完整性校验:依次执行 scripts/localize-links.mjs 和 scripts/check-translation-integrity.mjs。
- 构建站点并开 PR:
npm ci && npm run website:build(见 package.json 的website:build脚本),通过后创建带docs标签的 PR,从不直接推送main。
其中几个工程细节值得展开:
重试与失败容忍
翻译步骤在同一个 step 里循环尝试最多 3 次。模型偶发返回畸形 JSON 会导致单文件失败,而由于锁文件的存在,重跑只会补译缺失片段,成本很低。彻底失败的个别文件就直接留在未翻译状态——链接本地化和侧边栏回退机制保证部分翻译的 locale 依然可构建、可审查。
空产出保护
如果运行结束后 .lingo-src 下除了 en 之外没有任何翻译产物(例如 API key 失效或服务商故障),工作流会报错退出,避免"无改动可翻译"的静默通过。
隔离机制(Quarantine)
完整性校验或 markdownlint 未通过的页面会被隔离而非阻断整个运行:恢复到上一版本,或者从未有过版本就直接删除,并在 PR 描述中列出。设计意图是"40 页里 1 页坏了,不应该让 39 页好的全部作废";被隔离的页面缺失本身就是受支持状态(链接本地化与侧边栏会自动回退到英文)。第二轮校验必须通过,保证任何未经验证的内容都不会进入合并。
机器修复
翻译器的 Markdown 序列化器会把"仅含图片的链接"写成 5 行(、空行、图片、空行、),这会触发 markdownlint 的 MD034 并产生游离括号。工作流用 perl 一次性把它折叠回单行,再执行 scripts/align-tables.mjs 对齐表格列宽(翻译后的表格几乎无法保持源列宽,会触发 MD060),最后跑 markdownlint-cli2 --fix。未被 --fix 修复的残留由完整性步骤兜底隔离。
三、i18n.json:翻译引擎的完整配置
i18n.json 是整个流程的配置中枢,共四块核心内容:
locale:source为en,targets为["es"]。新增语言就在这里追加代码。buckets.mdx:指定翻译源为.lingo-src/[locale]/**/*.md,并给出四条lockedPatterns锁定正则,匹配到的内容逐字节保留:<Badge[^>]*>(VitePress 徽章标记)^:::\s*[a-z-]+(:::tip、:::warning等容器关键字行)\$[A-Z_]+(环境变量形态,如$VAR)\{\{[^}]*\}\}(模板插值)
provider:当前为openai+ 模型gpt-5.4,可整体替换为anthropic、google、mistral、openrouter或ollama,各自读取惯例的*_API_KEY环境变量;把整个 provider 块删除则改用 Lingo.dev 托管引擎(需要其账号)。prompt:向模型下达的系统指令,明确要求逐字节复刻以下内容:CLI flag 名(如--gh-webhook-secret)、环境变量(ATLANTIS_*)及其值、YAML/JSON 键、Terraform 块名与 HCL 标识符、文件路径/URL/链接目标/锚点、HTTP 动词与 API 端点路径、版本字符串与产品名(Atlantis、Terraform、OpenTofu、GitHub、GitLab、Gitea、Bitbucket),以及一切行内代码与围栏代码块中的内容。VitePress 专属规则包括:容器标记保留英文类型关键字只译标题文字;<Badge text="v0.45.0+" type="info"/>原样保留;相对链接连同.md扩展名与#anchor保持原样。翻译策略上要求"忠实而非意译":面向工程师的参考文档优先使用平实通用的术语,句子结构贴近源文,便于读者对照英文页;plan、apply、workflow、pull request等领域术语保持不译。
锁文件:增量翻译的核心
i18n.lock 是 Lingo.dev 的增量记忆,文件以 version: 1 开头,随后按内容片段给出 MD5 校验和(如 meta/layout: c227d2c8...、meta/hero/name: 0eeebf1e...)。原理是:每个英文片段在校验和不变时,直接复用既有译文;某一段变了,只有那一段重新翻译。这就是文档所称"编辑一个段落就只重译该段落,不碰其他内容"的底层机制,也是 workflow 重试成本极低、force 输入存在的意义所在。
四、链接处理:半翻译状态下如何不产生 404
VitePress 在构建时对失效的相对链接是直接报错的。翻译是逐页进行的,而翻译页会原样继承英文源里的相对链接——例如 runatlantis.io/es/guide.md 里写着 ./docs/installation-guide.md,就会解析到 runatlantis.io/es/docs/...,在对应页尚未翻译时直接构建失败。
scripts/localize-links.mjs 解决这个问题,规则只有一条:
若本地化目标存在,就指向它;否则用
../前缀指回英文树,让读者落到英文页而不是 404。
具体实现要点(与源码对应):
- 用两个正则分别覆盖 Markdown 链接/图片目标
](target)和文档中嵌入的原始 HTML 的src=/href=属性——这些文档为了表达 markdown 无法完成的内容(定宽图片、带行内图片的嵌套列表)会直接写 HTML; isExternal()先排除外部协议(http:等)、协议相对地址(//)和纯锚点(#),站点绝对路径(/开头)也原样保留;- 相对路径先
path.resolve到当前文件目录,若本地化文件存在则不改写;不存在则换算到英文树中同路径文件,再以相对路径写回(不足./前缀则补上),锚点原样拼接; - 若英文树对应文件也不存在,则保持原样不动,交给构建步骤去报错暴露问题。
导航栏与侧边栏采用同一套回退策略:在 runatlantis.io/.vitepress/navbars.ts 与 runatlantis.io/.vitepress/sidebars.ts 中,localizedLink() 通过 existsSync 检查 runatlantis.io/<locale>/<path>.md 是否存在,存在就链接到本地化页面,否则回退英文路径。侧边栏的 esLabels 还维护了一整套英文→西班牙语的菜单标签映射,而博客文章标题复用 runatlantis.io/es/blog.md 中的既有措辞,保证同一篇文章在读者面前只有一个标题。站点级的 locale 注册、UI 文案(导航/页脚/搜索占位符等)则集中在 runatlantis.io/.vitepress/config.ts 的 locales 块中。
顺带一提:DocSearch 的
/es/搜索占位符已在 config.ts 中配置,但搜索结果仍为英文——配置中的注释明确指出,让/es/以langfacet 进入索引需要在 Algolia 的爬虫侧修改配置,而非站点代码。
五、完整性校验:八个维度的严格比对
scripts/check-translation-integrity.mjs 逐页把译文与英文源比对,任一维度漂移即判定失败。它覆盖的翻译目录与 i18n.json 的 include 一致:docs、guide、blog、contributing(均递归),以及顶层页面(仅非递归)。
八个检查维度如下:
| 维度 | 检查内容 | 说明 |
|---|---|---|
| 围栏代码块 | 数量与逐字节内容 | 含 info 字符串,必须完全一致 |
| 行内代码 | 行内代码 span 集合 | 按多重集合比较,缺失会列出前 5 个 |
| 链接目标 | 数量 + 解析后目标 | 允许 localize-links 的合法改写,不允许任意重定向;锚点也须一致 |
| 容器关键字 | :::tip 等关键词序列 |
按顺序整体比较 |
<Badge> 标记 |
完整标记串 | 多重集合比较 |
| 标题数量 | #~###### 标题计数 |
防止译文增删章节 |
| frontmatter 键 | 键集合排序比较 | 防止键被翻译 |
| frontmatter 结构值 | layout、aside、outline、sidebar、navbar、editLink 的值 |
VitePress 解释而非渲染的值,严禁翻译 |
代码实现上有几个值得注意的工程决策:
- 逐行扫描围栏而非整文档正则:文档正文中可能引用字面的 ``` 序列,一旦某行恰好以它开头,整文档正则就会误判为围栏起点导致后续全部错位。按 CommonMark 规则,反引号围栏的 info 字符串不得包含反引号,这正是区分两种情况的判据,因此
splitFences()采用逐行状态机;未闭合的围栏仍视为有效内容(其中可能有真实代码)而保留。 - 链接在解析后比较:本地化链接脚本把
./docs/x.md合法改写为../docs/x.md,因此比较双方先各自resolveTarget()解析成绝对路径 + 锚点,允许译文链接解析到英文源同一文件或该文件的 locale 内对应文件,其余情况一律报"指向了别处"。 - frontmatter 与正文分离:frontmatter 单独比较,正文比较前先剥掉 frontmatter,避免 YAML 注释被误当成标题。
- 原文无对应译文不算失败:遍历源文件时若目标文件不存在,直接跳过——"还没翻译"是受支持状态。
该脚本不仅跑在 translate-docs 工作流里,也跑在 .github/workflows/website.yml 的 Website Check 任务中:任何 PR(包括人工直接改 locale 目录的 PR)都会触发同一套校验,保证手工编辑与机器产出接受同等检查。Website Check 同时还会跑 typos 拼写检查、Vale 散文风格 lint(api-endpoints.md 因刻意使用 Github/Gitlab 字面值而排除)和 lychee 链接检查。
六、本地复现:在你自己的机器上跑通整条链路
无需改动仓库,任何具备 Node 环境的开发者都可以在本地复现翻译与校验流程:
# 1. 翻译(需要提供商 API key,见 i18n.json 的 provider 块)
export OPENAI_API_KEY=...
npx lingo.dev@0.138.4 run
# 2. 修复半翻译 locale 中的链接,然后校验
node scripts/localize-links.mjs es
node scripts/check-translation-integrity.mjs es
# 3. 真正的门槛:VitePress 构建,死链接在此暴露
npm run website:build
对应地,package.json 中提供了 npm run website:dev(本地 8080 端口开发预览)与 npm run website:build 两个脚本。scripts/localize-links.mjs 与 scripts/check-translation-integrity.mjs 均支持一次传入多个 locale(node scripts/check-translation-integrity.mjs es,扩展为 es fr ... 亦可),并按脚本自身约定输出 Link localization complete 或 Translation integrity: N file(s) checked, no problems found. 之类的结论,校验失败时进程以非零码退出。
七、新增语言:四步接入与一条重要约束
文档明确给出了新增 locale 的标准操作:
- 在 i18n.json 的
locale.targets中追加语言代码; - 在 runatlantis.io/.vitepress/config.ts 中新增 locale 条目及其 UI 文案(导航、页脚、搜索占位等);
- 在 navbars.ts 和 sidebars.ts 中补充标签映射(
localizedLink回退逻辑自动生效); - 用
workflow_dispatch手动触发一次 .github/workflows/translate-docs.yml。
同时有一条明确警告:一次只加一种语言。每种语言都会成倍放大链接检查面,更重要的是放大审查负担——一个没人能审查的语言版本,比没有这个版本更糟。这与整条流水线的设计哲学一脉相承:机器翻译的质量上限由人工审查兜底,宁可慢、宁可部分回退英文,也不允许未经验证的内容上线。
八、审查翻译 PR:维护者应该盯住什么
机器翻译在参考文档上最容易出错的地方,正是文档明确要求审查者聚焦的部分:
- flag 名、环境变量、YAML 键与文件路径被留在英文——翻译器可能擅自意译,而这类标识符一旦被改动,读者照抄就会出错;
- 命令输出与代码示例被改动——虽然完整性校验强制保证代码块逐字节一致,但审查者仍应通读确认;
security.md、server-configuration.md以及一切涉及凭据的页面——值得逐字细读而非扫读,这是机器翻译翻车代价最高的区域。
作为佐证,工作流创建的 PR 描述本身也带着同样的提醒,并附上"仅重译了英文源发生变化的片段,其余来自 i18n.lock"以及"校验器与 VitePress 构建已在任务内运行"等说明,同时把被隔离的页面列表写进 PR body,供审查者决定是否需要人工修复后重跑。
九、更换模型或提供商:最小改动原则
provider 块是 i18n.json 中最易调整的部分,支持 openai、anthropic、google、mistral、openrouter、ollama 六种,各自读取其惯例的 *_API_KEY 环境变量;整个块删除则切换到 Lingo.dev 托管引擎(需要账号)。
密钥管理上,翻译用的 key 存放在名为 docs-translation 的 GitHub environment(环境)中而非仓库 secret,因此只有 translate 这一个 job 能读到它(环境还受部署分支规则限制);它归属于提供商侧一个独立的、带消费上限的服务账号和项目,需要轮换时不会牵连其他用途。{source} 与 {target} 两个占位符由 CLI 在执行时替换为 locale 代码注入 prompt。
关于模型选择,文档给出了一条刻意为之的决策:当前模型故意用 mini 档。因为代码已被剥离,翻译一个 200 词的段落并不需要 frontier 级模型,真正保证正确性的是后置的完整性校验体系。这也解释了为什么 pipeline 愿意把"模型出错"当作日常事件来设计(重试、隔离、回退三件套),而不是寄希望于模型永不犯错。
十、总结:这套流水线给文档国际化带来的启示
Atlantis 的翻译流水线是一套可复用的工程范式,其核心可以概括为三点:
- 可执行内容零改动:代码块、标识符、链接目标通过 AST 跳过与锁定正则、prompt 指令、完整性校验三重防线保护,机器翻译永远碰不到"照抄会出错"的内容;
- 增量而非全量:
i18n.lock按片段校验和实现"改哪译哪",让重试、按需翻译与成本控制成为可能; - 降级而非阻断:链接本地化 + 导航/侧边栏回退 + 页面隔离,使"部分翻译"成为一等公民状态——读者永远落到一个可读的页面,维护者永远拿到一个可审查的 PR,而唯一的事实权威始终是英文源。
如果你想深入这套实现的细节,仓库内最值得精读的四个文件是 .github/workflows/translate-docs.yml(完整流程与隔离逻辑)、scripts/localize-links.mjs(链接降级规则)、scripts/check-translation-integrity.mjs(八维校验实现)以及 i18n.json(引擎与 prompt 配置);已有的西班牙语文档可从 runatlantis.io/es 开始浏览。