翻译规则
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））；翻译为英文时，使用通行的英文类别名。指目录或文件本身时保留代码体英文。
结构保持
配对门禁会检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起始编号、列表项数量、链接 locale 与语义目标；门禁未覆盖的结构仍需人工核对。两个配对文件必须在以下方面一一对应：
- 标题层级（相同级别、相同顺序；标题的文字要翻译）；
- 列表形态与编号；
- 表格（相同的列、相同的行序；表头单元格按术语表翻译）；
- 围栏代码块：逐字节一致，包括注释。配对签名比对信息字符串与内容，
```ts块还要通过doc-typecheck编译； - 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；
- 链接与锚点：每个相对文档链接必须保持相同的语义目标和完全相同的 query/fragment 后缀。目标属于活跃双语语料时，英文侧使用其
.md路径，中文侧使用其.zh.md路径；该范围内缺少对侧属于错误，范围外的目标保留原路径。外部 URL、图片与纯页内 fragment 保持不变。语言切换行仍是显式跨 locale 例外；在 GitHub 以外位置渲染的 README 可以按 README.md 的规定，使用指向确切对侧文件的规范公开仓库 URL。链接文字翻译。
本仓库的 Markdown 约定对 .zh.md 文件原样生效：一个段落一个物理行（verify-md-wrap）、相对链接必须可解析（verify-md-links）、文件末尾恰好一个换行。
术语
- terminology.md 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。译成中文时，采用「中文」列，并按「首次出现」列括注；译成英文时，采用「English」列，不加中文括注。
- 译成中文时，术语表未收录的技术术语只有在主流中文 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的其余门禁。这些门禁会检查一致性记录、切换行、标题深度、代码块、表格行列数、列表类型、有序列表起始编号、列表项数量、链接及仓库 Markdown 规则；列表与表格的顺序、非常规列表编号、行内代码、强调标记、语义、术语和语体则由人工评审负责。
参考资料
本文各规则引用的权威出处，供想了解底层依据的人和 agent 查阅：
- 中文文案排版指北：中西文混排空格与标点的社区事实标准。
- MDN 简体中文翻译指南：与本文同形态的仓库内置翻译规则文件；空格、标点与术语表实践。
- Kubernetes 中文本地化指南：最大的中文本地化团队的术语首现与标点实践。
- Vue.js docs-zh-cn 翻译须知：逐术语的译／留决策与语气。
- zh-style-guide：社区中文技术文档写作规范，本文借用了它的规则级别分类体系（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。
- W3C clreq 与微软简体中文风格指南：排版学与厂商本地化的正式基线。
- GB/T 19682-2005《翻译服务译文质量要求》：国家标准；本文「忠实性」与「术语」两节将其三项基本要求（忠实原文、术语统一、行文通顺）落实为可操作的规则。