夜雨聆风Photo by young ho seo on Pixabay
作为一名同时要维护中英文、并且还要维护日文文档的技术文档工程师 (Technical Writer)，我曾经被不同语言之间的文档翻译与同步这件事反复折磨。
本文跟大家分享一个实践证明不错的解决方案。如果你对方案感兴趣，可以往下看并通过我的开源项目了解实现细节：
https://github.com/qiancai/ai-markdown-translator
多语言文档维护的那些痛点
在那个还没有 AI 的时代里，在处理产品的中英文文档更新时，我只能手动互相同步，在处理日语文档翻译时，则依赖机器翻译（简称机翻）和手动修正。
双语文档双向同步的痛点
因为历史原因，我参与维护的产品的中文和英文文档分别存放在两个不同的 GitHub 仓库中。
由于文档贡献者的母语不同，有的贡献者选择向中文文档仓库提交 PR（拉取请求，即 Pull Request，以下简称 PR），有的选择向英文文档仓库提交 PR。
不同语言的文档 PR 的创建和合并时间可能不同，导致有的文档英文版稍微领先，有的文档中文版稍微领先。因此，在某段特定时间内，对于某些文档，中英文文档并不是严格逐行完全对应的。
为了保持中英文文档的同步，当贡献者只创建了某一个语言的文档更新 PR，且该 PR 完成所有审核和优化后，文档工程师就需要去另一个语言的文档仓库创建对应的翻译 PR，并根据源语言 PR 的文档更新，翻译并更新目标语言的文档。
比如中文 PR 在一个有 1000 行的 Markdown 文件里的某个位置新增了 7 行变量描述，文档工程师也需要在英文文档里定位到对应的位置，翻译新增的变量描述，添加到目标语言文档里的对应行，且保持源语言文档未涉及更新的地方在译文中的内容和 Markdown 格式也不变。
这个事情听起来虽小，涉及的手动操作却非常繁琐，例如建分支，定位要更新的文档，定位要更新的行，添加翻译，提交改动，添加 PR 标题、描述，设置 PR 标签等等。
当每天需要处理大量类似的重复任务时，任何人都很容易陷于这些琐事中，无暇顾及工作中更有意义和价值的事情。
多语言文档定期同步的痛点
除了中英文文档外，目前我也在维护日语文档的翻译与同步更新。
好几年前刚开始引入产品的日语文档时，我们用的是 Google Translate 机翻，每周定期将 Markdown 文档从英文翻译为日语，但是机翻经常出现翻译错误、格式混乱（Markdown 链接可能被改坏、代码块可能错乱、表格可能错位）、误译本不应翻译的变量和参数、内容生硬等问题。
为确保文档能够顺利构建，我们在飞书群里添加了一个监视文档构建的 bot，如果遇到构建失败，bot 就会自动发送一条包含构建失败链接的消息到飞书群。
于是，只要某周有较多日文更新，bot 就会发消息说文档构建失败了，然后我们就需要额外花时间 debug 构建错误，修复日语翻译的格式问题。
一位日本技术支持同事经常热心帮忙审校日语翻译，纠正了不少翻译错误。但很糟糕的是，当时的机翻工具在处理文档时，即使源语言 Markdown 文档只修改了一行，翻译工具也会把整个文件重新翻译，这导致之前已经审校修正后的内容被覆盖，需要重新审校和修正。
这种感觉，就像你辛苦写完一篇论文，反复修改完善草稿后，第二天却发现修改版被旧稿覆盖，前功尽弃，只得重写一遍 😔
此外，日语翻译术语维护也很麻烦，因为采用的是 Google Translate，每次术语有更新，都要去 Google Translate 的控制台手动更新术语表，这导致术语表容易出现更新不及时的问题。
解决思路：不要全文重翻，只同步源文档的变化
怎样才能在兼顾翻译质量和效率的同时，解决上述痛点呢？
我的核心思路是：
先通过确定性逻辑自动识别变化，再由 AI 只处理和翻译真正需要更新的内容。
围绕这个思路，我搭建了一套 AI 多语言文档处理工具链，包括：
自动创建翻译 PR 的脚本 自动触发翻译的 GitHub Actions 工作流 核心的翻译引擎 ai-markdown-translator
下面我将分两个场景来介绍这套工具链带来的解决方案。
由于不同产品文档的多语言维护策略不同，你可以按需阅读你感兴趣的场景及对应方案：
如果产品文档经常涉及中、英文文档的双向同步，可以参考下面的“场景 1：中英文文档更新的双向同步”。 如果产品文档维护是以某一种语言为主（例如英语），其他多个语言都只需要跟随主语言定期同步更新即可，可以参考下面的“场景 2：独立的日语全链路自动翻译”。
场景 1：中英文文档更新的双向同步
针对当前产品的中英文文档都是通过 PR 来 track 更新的特点，我设计了一套以 PR 为中心的自动化工具链。
在源语言 PR 上，一键自动创建空的翻译 PR。 在翻译 PR 创建后，自动触发翻译任务。 根据 PR diff 分析结果自动定位目标语言文档的对应章节。 加载翻译术语。 调用 AI 翻译引擎进行翻译。 将翻译结果更新到目标语言 PR 中对应文档的对应章节。 译后检查，并自动将翻译结果反馈到翻译 PR 中。
以下是具体实现方案：
1. 自动创建翻译 PR
创建 PR 本身是一系列固定的操作，虽然步骤挺多，但也比较容易实现。
这里有一个关键问题：自动创建翻译 PR 的入口放在哪里？
最开始，我维护了一个本地的 Python 脚本，每次使用前都需要先在本地脚本中手动指定源语言 PR 的链接，然后才能执行脚本，脚本会自动创建翻译 PR。
后来我发现这样也挺麻烦的，因为我需要先到 GitHub 网页上复制 PR 链接到本地，再在本地执行脚本，最后再回到 GitHub 网页上查看 PR 是否创建成功。
要是能在 GitHub 网页上直接点击一次按钮，就能自动创建翻译 PR，那不是更方便吗？
带着这个思路，我将自动创建翻译 PR 的脚本转成了 JavaScript 代码，集成到了团队中已经启用的一个油猴 (Tampermonkey) 脚本中。
这里给不太熟悉油猴脚本的同学简单介绍一下：Tampermonkey 是一款浏览器扩展，可以用来运行用户脚本；安装后，可以在你的浏览器中运行自定义的 JavaScript 代码，修改特定网页的内容，并且自动化浏览器相关操作。
下图是启用油猴脚本后的效果，文档仓库的 GitHub PR 页面上 PR 标题的右侧现在新增了一个我们定制化的 Create Translation PR 按钮，并且有两个子选项供我选择：
如果源语言文档 PR 涉及用户文档更新，且需要由 AI 自动翻译，点击 Create Synced Translation PR。 如果源语言文档 PR 不涉及文档内容同步，只做了仓库特有配置等更改，可以点击 Create Empty Translation PR，后续内容修改再自己单独完成。
有了这个定制化按钮后，只需要在源语言文档 PR 页面上按需点击其中一个选项，脚本就会自动读取源 PR 的标题、描述、标签、分支等信息，然后完成下面的操作：
同步目标仓库的基础分支，建翻译分支。 创建目标语言 PR，并填写 PR 标题、描述。 在 PR 描述中加入源 PR 链接，根据源语言 PR 的标签，为翻译 PR 添加合适的 label。 根据你点击的是 Create Synced Translation PR 还是 Create Empty Translation PR 按钮，决定是否自动触发翻译任务，并自动将源语言 PR 的更新同步到翻译 PR 中。
以前需要手动点十几下的操作，现在被压缩成了一次点击。粗略估算了一下，平均每个 PR 可以节省 2-3 分钟的时间。别小看这几分钟，如果每天有 10 个翻译 PR 需要创建，一年就可以节省几十上百个小时的时间。
可能有人会问，为什么需要这个按钮呢？在源语言 PR 创建的同时自动创建一个翻译 PR，不是更省事吗？
其实这取决于源语言文档 PR 创建后，还有什么后续步骤。为了确保文档的准确性和易用性，我们的 PR 通常会由技术团队进行 tech review，并由文档工程师进行内容质量优化，在这个过程中，文档 PR 的内容可能经历多次修改。
如果太早自动创建翻译 PR，不仅会造成中英文文档之间需要频繁同步，还会造成两个 PR 之间更新不一致的风险。因此，我通常会在源语言 PR 完成所有的审核后，再在 GitHub 网页上点击一次定制按钮，创建翻译 PR。
也会有人问提，为什么不在源语言 PR 合并的时候自动触发创建翻译 PR 呢？
因为对于固定发版周期的新功能文档，合并 PR 意味着对应文档自动上线，但是我们的产品发版要求中英文新功能文档同时上线，而且我们经常也在 review 翻译 PR 的时候发现源语言 PR 的一些问题，于是需要去源语言 PR 也同步修正。
2. 自动触发翻译任务
翻译 PR 已经创建好，翻译任务也已经触发，接下来怎么把源语言 PR 的更新同步到翻译 PR 中呢？
以中文同步到英文为例，我在英文文档仓库创建了一个 GitHub Actions 工作流 sync-doc-pr-zh-to-en.yml。
在这个工作流中，可以定义翻译任务的基本信息，例如：
源语言和目标语言 AI provider 和 AI API （一般可通过环境变量配置） 翻译范围（可以指定只翻特定文件夹内的文档，也可以指定只翻特定 TOC 目录内的文档） 翻译引擎路径 （即 ai-markdown-translator路径）翻译术语路径
如果你不熟悉 GitHub Actions 工作流，可以简单理解为它是 GitHub 上的一个可以自动化执行的脚本，可以按照你设定的条件定时或按需自动执行。
当通过 Create Synced Translation PR 按钮创建翻译 PR 时，会自动触发这个 GitHub Actions 工作流进行下面的操作：
检查 PR 地址和仓库是否正确，获取目标翻译 PR 的真实分支，并确认该分支可以被推送。 通过检查后，它会 checkout 目标分支，运行翻译引擎 ai-markdown-translator翻译英文文档中需要更新的内容，再把生成的增量修改提交并推送到目标 PR。无论执行成功或失败，都会在目标 PR 中留下状态信息。
下图是在点击 Create Synced Translation PR 后，脚本在 GitHub 返回的进度对话框示例，它会先创建一个空 PR，然后触发翻译工作流调用 ai-markdown-translator 进行翻译。
翻译完成后，工作流会在目标语言 PR 上自动添加一个内容提交，加入更新后的内容。
打开 PR，你将看到，源语言 PR 改了什么，目标语言就改什么。
即使只源语言更新一个单词，翻译也能做到精准同步，不会修改译文中其他的行或句子，也不会贸然修改原来同一个句子中其他词语的翻译，保持推文 Git diff 与 源语言 Git diff 除了语言其他都一致。
例如：某篇文档有 150 行左右，中文只更新了一个单词：
经过 ai-markdown-translator 处理后，对应的英文也会按照 context 只更新对应的词：
这个工作流非常适合日常中英文文档双向同步，因为源 PR 和目标 PR 之间有清晰的对应关系。
3. 自动反馈翻译结果
翻译引擎 ai-markdown-translator 在处理文档翻译时，会基于源语言和目标语言的对应关系，源语言的更新范围，以及现有译文中受影响的部分，来确定目标语言要翻译并更新的内容。
如果其中任何一个环节出现问题，比如 AI 翻译失败或脚本将翻译后的内容写入到错误的位置，将会导致翻译结果出问题。
因此，翻译完成后，无论是成功还是失败，这个 GitHub Action 工作流都会在翻译 PR 上加一条 comment，提示翻译结果的状态。
场景 2：独立的日语全链路自动翻译
和中英文文档双向同步不同，针对日语文档，我建立了一个从英文文档到日语文档的全链路自动翻译和更新工作流。
这个工作流会在每周三晚上自动运行一次。它会读取一个包含英文文档提交信息的游标文件，获取上一次已经同步到过日语的英文 commit，再找到英文源分支的最新 commit。
这两个 commit 之间的 Git diff 涉及的文档更新，就是本轮需要翻译的内容。
接下来，工作流会自动完成整条链路：
分别 check out 英文的文档分支，以及日语的文档目标分支。 计算源 commit 范围，筛选本轮需要处理的文件。 调用 ai-markdown-translator按需加载英日术语表，并做增量翻译。启用译后自检流程，验证翻译后的文档是否与源文档匹配。 针对本周的所有英文变更，统一创建一个日语翻译 PR，仅针对英文文档中发生变化的内容，对应更新日语文档。 在 PR 中记录源 commit 范围、文件列表和翻译自检结果。
第二天早上打开 GitHub 时，我通常已经能看到一份待审核的日语翻译 PR，以及翻译自检信息。
如果某些文件翻译失败，PR 中会保留失败清单。我可以指定文件重新运行工作流。
这个工作流也支持指定某些文件不参与翻译，或者指定仅翻译某些文件，满足不同语言定制化的翻译需求。
这条链路的重点是“机器发现变化，机器创建任务”，人只负责最终审核。相比之前无论源语言更新多少内容、目标语言都需要全文重翻的方式，目前新的这个工作流极大地减少了日语翻译 PR 的审核负担，提高了日语文档的翻译质量。
自动增量翻译的核心 ai-markdown-translator
前面的两个翻译场景中，虽然翻译的触发机制和入口不同，但核心的翻译调用都是通过 ai-markdown-translator 完成的。
ai-markdown-translator 是我的一个开源项目，从创建到现在已经经过了 9 个月的迭代（改了无数 bug 🤣），从最开始只能同步少量文档更新，到现在已经可以处理成百上千个 Markdown 文件的增量翻译，并保持了较高的翻译质量和效率。非常适合 “Docs as code" 维护方式的多语言文档之间的同步更新。
当一个工作流，比如 GitHub Action 工作流调用它时，它会根据工作流的输入自动判断是要翻译单个 PR 还是执行全链路自动翻译，然后根据不同的场景，自动调用不同的翻译逻辑，从而轻松实现“源语言文档改哪里，目标语言文档就同步改哪里”的目标。
场景 1：针对单个 PR 的翻译，它会分析源语言文档 PR 的 diff，判断更新类型，来进行后续的增量翻译和更新操作。 场景 2：针对全链路翻译，它会分析上一次已完成翻译的源语言文档 commit 和最新源语言文档 commit 之间的 diff，判断更新类型，然后来进行后续的增量翻译和更新操作。
整个处理过程中，ai-markdown-translator 遵循“能用代码处理的，就尽量通过代码处理”的原则。
涉及 AI API 调用的只有两个环节：一个是两种语言之间的文档结构匹配，另一个是 AI 翻译。其他的预处理和后处理部分都通过 Python 脚本完成，这样可以尽可能地降低 AI 调用成本，并提高翻译的准确度和效率。
更多的实现细节就不在这里展开了，感兴趣的同学可以查看项目文档：
https://github.com/qiancai/ai-markdown-translator
此外，为了确保翻译符合产品术语规范，ai-markdown-translator 也集成了术语表处理逻辑。
你可以为中英双语之间的互译维护一份术语表，并在你调用 ai-markdown-translator 时指定术语表的路径作为输入。
术语表需要以 Markdown 表格的形式呈现，包括源语言和目标语言的列。同时，你还可以在术语表中添加一列翻译说明供 ai-markdown-translator 作为翻译参考。例如，某个词翻译后是否保留英文、产品名应该采用什么大小写、某个译法只适用于什么场景等。
ai-markdown-translator 不会每次都把完整术语表塞给 AI。它会先检查当前文档里出现了哪些术语，只选出相关条目交给 AI。这样既能保证术语使用的一致性，又不会因为术语表越来越大而浪费大量 token。
术语表也因此从一份“给译者查阅的参考资料”，变成了可以直接参与自动化流程的质量规则。
这条 AI 增量翻译工具链的优势
根据我这半年多以来的实践和总结，在产品的多语言文档维护中，这条 AI 增量翻译工具链具有以下优势。
译文一致性更好：基于 Git diff，实现精准翻译，翻译范围从“整个文件”缩小到“发生变化的内容”，已经人工润色过且此次未涉及更新的内容可以继续保留原样。 调用成本更低，生成速度更快：只给到 AI 尽可能精简但上下文充分的输入，也只让 AI 生成必要的输出。相比全文翻译，可以降低约 40% 成本。 翻译结果更容易审校：译文审校者不用在整篇文档里找变化，译文的 Git Diff 更干净，审校者只需要检查本次真正更新的内容。 术语集成让翻译结果更加准确和稳定：根据当前文档涉及的术语按需加载，新译文可以沿用既有的术语译法。 失败变得一目了然，也更容易处理：工具会对翻译进行自检，并输出失败报告和结构异常信息。工作流可以把这些信息放进 PR，直观明了。
当然，AI 输出仍然需要审核。自动化做的是缩小风险范围，我们没法假设格式问题从此不会发生。
AI 增量翻译工具链 vs AI agent
2026 年春节以来，随着 AI agent（例如 Codex 和 Claude Code）在工作中的使用越来越广泛，我也尝试了将现有的 AI 增量翻译工具链固化为一套 Skill，由 AI agent 调用。
但发现完全由 AI agent 处理的话，涉及少量更新的 PR（比如只更新了两三个文件的 PR）， AI agent 处理起来效果尚可，但是涉及多文件更新的 PR 比如更新了十几个甚至二十多个文件的 PR）则效果不佳，会出现下面的问题：
AI agent 耗费时间长是 AI 增量翻译工具链的 3 到 5 倍，特别是针对多个文档的更新 由于 AI agent 在处理翻译的整个过程中，还需要去读取更多的上下文信息，消耗的 token 更高，意味着花费更高 偶尔出现源语言中未更新的行也在目标语言文档中被更新的情况
此外，AI 增量翻译工具链易用性更胜一筹：针对中英文双语同步场景，我只需要在 GitHub 网页上点一个按钮，不需要复制粘贴任何内容给到额外的 AI agent，就可以完成处理。针对日语全链路自动翻译场景，本就无需任何额外的人工操作，工作流会自动定时发起翻译和更新。
因此，目前大多数场景下，在完成源语言 PR 的审核和优化工作后，一键触发 AI 增量翻译工具链依然是我的首选。
当然，对于一些改动很小且无需反复审核的文档更新，直接由 AI agent 同时创建双语 PR 也是一种不错的选择。
这套方案可以在其他项目中复用吗
虽然这套 AI 增量翻译工具链最初是为 GitHub 和 Markdown 文档设计的，但它背后的思路并不局限于某个项目，也不仅仅局限于 Markdown 文档。
增量优先于全量：只要存在“大文件、小改动”，diff 就是成本最低的信息源。它不仅适用于翻译，也适用于内容同步、版本迁移和批量维护。 能用代码确定的，不交给 AI 猜：文件增删、diff 解析、章节结构、分支操作和 PR 创建，都尽量由确定性代码完成，而 AI 主要负责处理脚本无法完成的部分。 已有内容也是上下文：很多 AI 翻译方案只关注源文档，却忽略目标仓库里已经存在的译文。对持续维护的多语言文档来说，已有译文往往是最有价值的参考资料，可以帮助 AI 更好地理解上下文，提高翻译质量。
如果你也在维护多语言的技术文档，希望本文能对你有所启发，也欢迎大家提建议交流。
