deepseek-harness/docs/i18n/translation-rules.zh.md

翻译规则

English | 中文

本文规定：如何在本仓库文档配对的中英文两种语言之间进行翻译。两种语言同权（见 README.md）：每次变更可以用任一语言撰写，被编辑的一侧即为本次更新的源；本文的规则约束如何产出或更新对侧文件。这些规则对人类和 agent（智能体）同等生效；应用这些规则的仓库内置 agent 工作流是 .agents/skills/dsh-translate-docs。规则级别沿用 RFC 2119 的用法：必须（MUST） ／ 禁止（MUST NOT） 会卡门禁或评审；应当（SHOULD） 偏离时要说明理由；可以（MAY） 自行裁量。

忠实性

• 对侧文件必须传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。
• 对侧文件读起来应当是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。
• 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。

行文

• 语体以 style-samples.md 为校准锚点——人工定稿的金标样例按文体各一组，译文必须对齐最接近的样例语体；样例与本文条款冲突时，以样例为准。目标语体是规范的技术制度文：完整主谓、确定语气，不口语化也不学术腔。
• 以母语技术作者的身份重述内容，而不是逐句转写的译者。写完后逐句对照原文核验：不添加、不遗漏——流畅永远不是丢掉语义成分的理由。
• 给句子补显式执行主体：英文的被动句和抽象主语，中文写成「系统、门禁、评审人」等实际执行者做主语。
• 优先使用中文工程惯用语而非直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻做本地化替换而不是移植，英文名词链展开为动词句。
• 长段按语义单元拆分，一段一件事。段落边界可以与原文不同；结构签名不比对段落数。
• 类别名词说中文并在首现括注英文（实操手册（cookbook））；指目录或文件本身时保留代码体英文。

结构保持

结构一致性由配对门禁负责校验，译者无需为保持结构而牺牲行文的流畅：在既定框架内自然书写即可。配对的两个文件必须在以下方面一一对应：

• 标题层级（相同级别、相同顺序；标题的文字要翻译）；
• 列表形态与编号；
• 表格（相同的列、相同的行序；表头单元格按术语表翻译）；
• 围栏代码块：逐字节一致，包括注释。代码属于受验证的范围（```ts 块要通过 doc-typecheck 编译），而被改动的注释是代码块计数门禁看不见的漂移；
• 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；
• 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 .md 路径而非 .zh.md 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。链接文字翻译；链接目标不翻。

本仓库的 Markdown 约定对 .zh.md 文件原样生效：一个段落一个物理行（verify-md-wrap）、相对链接必须可解析（verify-md-links）、文件末尾恰好一个换行。

术语

• terminology.md 是双向的术语真源。翻译前请先加载它；翻译过程中，表内的每个术语都必须严格按表中规定的译法呈现，包括首次出现的括注（如首现写 agent（智能体），之后写 agent）与「不要译作」的禁项。中文先行撰写时，英文对侧同样按表中英文列使用术语。
• 表中没有的技术术语，只有当某个主要中文 OSS 或厂商文档已有成型译法时（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档）才可以翻译。请在 PR 中注明先例出处。
• 没有成型先例的术语，译文中必须保留英文，并且必须在 PR 描述的「待定术语」下列出，附上建议译法交评审者定夺。禁止就地发明中文译法，因为无先例的翻译恰恰会制造术语表要防止的歧义。确定下来的术语随后在同一个 PR 或后续 PR 中进入 terminology.md。

排版

本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 AGENTS.md）。以下中西文混排规则遵循 MDN 简体中文翻译指南、Kubernetes 中文本地化指南、Vue.js 中文翻译须知 与中文文案排版指北的跨项目共识，其根据是 W3C clreq 与 GB/T 15834—2011：

• 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：每个 plugin 注册 3 个 tool。全角标点与任何字符之间不加空格。
• 中文行文必须使用全角（中文）标点：，。：；？！（）「」。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（3.5、1,024）。
• 顿号：中文的并列项之间使用顿号（、），而非逗号。
• 禁止使用全角数字或全角拉丁字母：永远不写 １２３，永远写 123。
• 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek。除非引用代码，否则绝不写 github／Github。
• 第二人称用「你」，不用「您」（与 Vue、Kubernetes 中文约定及本仓库的直接语气一致）。
• 强调标记（**加粗**、*斜体*）落在与对侧相同的文字段上。中文没有斜体，渲染效果可能看不出差别，不要用引号或其他装饰替代。

质量标准

• 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。
• 交付前，请对照本文自查一遍，并单独通读对侧文件，不与源侧对照；不对照原文时，更容易察觉别扭的表达。
• 机械契约（一致性记录、切换行、结构、折行、链接）由 pnpm run verify-translation-pairing 和 doc-sync 的其余门禁检查。请运行门禁；门禁已覆盖的内容无需手工核对。

参考资料

本文各规则引用的权威出处，供想了解底层依据的人和 agent 查阅：

• 中文文案排版指北：中西文混排空格与标点的社区事实标准。
• MDN 简体中文翻译指南：与本文同形态的仓库内置翻译规则文件；空格、标点与术语表实践。
• Kubernetes 中文本地化指南：最大的中文本地化团队的术语首现与标点实践。
• Vue.js docs-zh-cn 翻译须知：逐术语的译／留决策与语气。
• zh-style-guide：社区中文技术文档写作规范，本文借用了它的规则级别分类体系（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。
• W3C clreq 与微软简体中文风格指南：排版学与厂商本地化的正式基线。
• GB/T 19682-2005《翻译服务译文质量要求》：国家标准；本文「忠实性」与「术语」两节将其三项基本要求（忠实原文、术语统一、行文通顺）落实为可操作的规则。