双语文档不走样：DeepSeek Harness 翻译规范

在开源项目里同时维护中文和英文两份文档，是件容易失控的事：英文改了中文没跟上，术语两边各翻各的，排版风格慢慢漂移，最后读者搞不清哪边才是准的。DeepSeek Harness 的做法是把「翻译怎么管」本身写成一份成文规范，放进仓库的 i18n 文档目录，人和 AI agent 一起遵守。本文拆解这份规范的核心内容，多数做法可以直接搬到其他双语文档仓库。

两种语言同等权威

规范开篇先定调：中英两个版本同等权威，任何一边都可以发起修改，改动在哪边成稿，哪边就是这次更新的源头，另一边按规范跟进对齐。规则同时约束人和 agent，并沿用 RFC 2119 的分级用词：MUST 和 MUST NOT 是闸门与评审的硬性阻断项，SHOULD 需要给出理由才能偏离，MAY 自行裁量。日常翻译在术语表引导下一次完成，只有用户显式调用时才启用更重的扩展翻译流程。

忠实：不加也不减

忠实的要求是双向的：对照语言不得新增任何行为、前置条件、警告、版本声明或示例，也不得丢掉原文已有内容。两个版本在事实上有出入时，不默认谁迁就谁，而是先修错的那一边，再在同一次改动里把另一边带齐。

忠实不等于逐字硬译。规范要求对照版本读起来是目标语言里自然的文字写作：按目标语法重组句子，保留作者原有语感，简洁的原文译完还得简洁。碰到依赖源语言习语的句子，译意思，不译习语。语气基准由人工认可的金标准样例锚定，样例与通用文风规则冲突时以样例为准。给句子补出明确施动者也是硬要求，中文尤其要少用模糊的被动句和抽象主语，让系统、门禁、评审人这些真实主体落到句子主语的位置上。

结构：交给门禁核对

这是整套规范里工程味最重的部分。仓库有一个配对门禁自动核对中英两份文件一比一对应：标题层级同级别同顺序，标题文本才翻译；列表形态和编号一致；表格列数与行序一致，表头按术语表翻译；代码块逐字节相同，连注释都不能动，其中的 TypeScript 代码还要能通过类型检查；行内代码里的命令、参数、配置键、文件路径、API 名和版本号原样保留，不翻译也不重排。

链接同样定死：所有相对链接在两个文件里必须指向同一个目标，约定一律指 .md 文件本身而不是某个语言变体，这样某一对文件先行落地时链接也不会悬空。中文侧唯一的例外是语言切换器。

术语：一张表说了算

terminology.md 是两种翻译方向共同的事实源。翻译前先加载它，表内每个词必须按行执行，包括「不要译作」栏目里的禁用译法。中文目标用中文列并在首次出现时附英文注释；英文目标用 English 列，不再附加中文注释。

表里没有的词也有路可走：中文可以引用主流中文开源社区或厂商文档的既有译法，比如 Kubernetes、Vue、MDN 的中文文档和微软简中风格指南，但要在 PR 里注明出处；没有先例就保留英文，挂进「待定术语」清单并给出建议译法。任何方向都不允许临时发明译法，定案后在同一次改动或后续跟进里把新词写回术语表。

排版：中西文混排细则

中文侧排版规则综合了 MDN 中文翻译指南、Kubernetes 本地化指南、Vue 中文文档翻译须知和中文文案排版指北等社区共识，并落到 W3C 中文排版需求与国家标准。几条硬规则值得直接抄：中文与拉丁词、中文与数字之间留一个半角空格；中文行文用全角标点，代码内、整句引用的英文和数字除外；并列项用顿号不用逗号；禁止全角数字和全角字母；专有名词保持规范大小写；第二人称用「你」不用「您」；加粗斜体标记跟随原文所在片段，中文没有斜体，也不要用引号替代强调。

质量：脚本加人审两道闸

一份翻译什么时候算完成？规范的标准是：一名双语工程师单独读任何一个文件，能获得另一个文件读者的全部信息，事实、注意事项、语气都在，且没有多余内容。达成靠两道闸：脚本闸门核对标题深度、代码块、表格行列、列表类型、链接有效性和仓库 Markdown 规则；语义、术语、语气、行内代码和强调这些机器管不了的部分，归人工评审。

值得抄的三件事

即使不维护双语文档，这份规范也有三样东西可以直接搬走。一是把规矩写成机器可查的闸门，能自动核对的绝不靠自觉；二是术语先行，一张带禁用译法的术语表比任何风格说教都有效；三是用 RFC 2119 分级标注规则强度，让 MUST 和 SHOULD 各自承担明确后果。文档质量从来不是靠译者细心，而是靠让不规范无法通过。