dsh-translate-docs

翻译 DeepSeek-Harness 文档

调用边界

仅当用户明确按名称调用 dsh-translate-docs 时，才运行此扩展工作流。对于常规文档工作、来自其他技能的工作，或根据推断得出的翻译需求，绝不要选择或加载此工作流；常规翻译遵循 docs/AGENTS.md 中的一次性、单遍规则。

此技能是什么

此技能是指导，而非翻译记忆库。 它是一份工作流指南，用于确保 foo.md ↔ foo.zh.md 成对文档在两种语言中都保持一致、自然。两种语言具有同等权威：更改可用任一语言编写，而该语言就是此次更新的来源。你是译者：以下规则说明必须满足什么要求，而非具体句子应如何措辞；措辞由你判断，术语则不容更改。

按更改类型分类——这决定其他所有事项

• 更新（文档对已存在，且其中一侧已编辑）：遵循更新路径。此路径由简报驱动，特意保持精简：不阅读指导语料，不追溯 Git 历史，仅对照文档做最小改动。应用更新时，绝不要重新翻译整篇文档——最小化更新可保留所有未更改内容经审核的措辞；重新翻译则会丢弃这些审核成果。
• 新增文档对（尚无对应文档）：遵循全文档路径。
• 删除或重命名文档：同时删除或重命名对应文档及其旁边的 .i18n.yaml 文件，否则门禁检查会报告文档对不完整。

.agents/notes/archived/ 下冻结的 Agent Notes 不属于翻译工作。其完整的三件套由归档验证器封存；归档后绝不要更新、重新记录或修复任一侧。

更新流程（由简报驱动）

由简报驱动的流程只需极低成本，即可达到与指导语料库相当的质量；已归档的 briefed-updates Agent Note 记录了基准测试证据。

1. 生成简报：pnpm run gen-translation-brief <any file of the pair>（不带参数时会为所有不同步的文件对生成简报）。简报会以最细且能安全对齐的粒度映射变更——先按变更的 Markdown 单元（段落、表格行、列表项、标题），再按整个标题章节，最后按整个文档——并包含自上次确认一致以来原文一侧的差异、每个变更单元最后一次确认时的原文、当前原文及当前对应文本（附行号）、变更涉及的术语表条目、首次出现位置的移动说明，以及具有约束力的更新规则摘要。
2. 仅有机械性差异？使用 --apply。 如果所有变更都位于文件对中逐字节相同的代码围栏内，简报会注明这一点；pnpm run gen-translation-brief --apply <pair> 会将编辑后的代码围栏拼接到对应文件中，并在写入前验证结构——无需子代理，也无需手动编辑。
3. 有散文差异？将简报（或生成简报的命令）交给子代理。 简报就是译者的全部工作材料——子代理无需重新阅读指导语料库（规则摘要、术语表条目，以及每个变更单元的三方上下文都已内嵌其中），也无需重新推导差异。只有在简报无法切实解答某个具体问题时，才查阅整篇文档流程中的权威依据——例如，周边文本中没有先例的未列出术语，或整篇文档简报（BOTH sides changed，或单元与章节均无法对齐）；这类情况始终需要依据 translation-rules.md 手动协调。
4. 以覆盖差异所需的最小改动为准。 保留差异未涉及的所有已审阅措辞，然后逐条核对变更片段与原文：不添加、不遗漏，术语遵循内嵌条目，代码片段逐字保留。
5. 按范围记录并验证：pnpm run verify-translation-pairing --write <pair>，然后运行 pnpm run verify-translation-pairing <pair>。--write 会精确指定你确认过的文件对——不带参数时会拒绝运行，因此批量重新记录必须显式使用 --all。整个语料库的检查仍会在 doc-sync/CI 中运行；不要在每次更新时运行。

整篇文档流程（新文件对）

需要从头开始编写译文时，负责协调的 Agent 不负责翻译：应启动子代理来完成翻译工作。译者先阅读下方的权威依据，然后将整个文件翻译成另一种语言——对于较长的文档，按章节翻译，并在翻译过程中保持每个章节的结构与原文一致，而不是最后再修正结构。

权威来源（阅读，不要重新概述）

• docs/i18n/README.md — 配对约定：三文件配对（foo.md、foo.zh.md、foo.i18n.yaml）、一致性记录中的分节哈希、语言切换器行、范围和排除项。
• docs/i18n/translation-rules.md — 翻译方式：忠实度、结构保留、术语规范、排版要求（MUST/SHOULD 级别）。
• docs/i18n/terminology.md — 术语表，双向均有约束力。翻译前就要加载，而不是等遇到不确定的术语时再加载；那些没有留意到的术语才最容易出现偏差。
• docs/i18n/translation-prompt.md — 自动化流水线经过校准、供机器使用的模板。使用此技能的 Agent 不会渲染该模板；术语表是自动渲染器唯一会注入的仓库文件，而此技能和 translation-rules.md 仍对 Agent 编写的译文具有约束力。
• dsh-prose-standard — 对正文覆盖范围和编辑判断的要求。应用于两侧文本，不得增删源文中的命题。

翻译

• 第 1 轮——撰写，而非逐字转换。 阅读一个语义单元，然后用母语技术作者的方式，根据最接近的风格示例重述。保留必要的结构框架，但不要强求逐句对应。
• 第 2 轮——逐分句对照源文核验。 在这一轮检查忠实度，而不是写作时：确认没有增删内容、每个术语都遵循术语表，并且每个代码片段都原样保留。通过用自然的方式重写句子来修正，而不是把词语硬补进去。
• 单独阅读完成后的对应文件。 对照源文后，不看源文单独阅读译文，并改写只有脱离源文后才显得生硬的表述。
• 只将最终文本写入文件，绝不写入草稿或笔记。
• terminology.md 中的每个术语都必须严格按规定呈现。目标语言为中文时，使用中文列和首次出现列；未列出的术语必须有可引用的中文开源软件／供应商先例，否则在「待定术语」中保留英文。目标语言为英语时，使用英文列和公认的英语技术术语；对含义模糊的源术语，保留原文并附上简短释义，同时将其列为待定术语。切勿在正文中自行创造译法。
• 配对文件中的代码块必须逐字节相同，包括注释。仓库相对文档链接必须保留相同的语义目标和完全一致的查询／片段后缀：活动双语语料库中的目标在英文侧使用 .md，在中文侧使用 .zh.md；缺少范围内的对应文件属于错误；语料库之外的目标保留其原有路径；切换器则是跨语言环境的例外。在第 2 轮中，需手动核验列表和表格顺序、非规范列表编号、行内代码、强调、含义、术语和语气。

查找待处理内容

• pnpm run verify-translation-pairing --list 会将所有范围内的文档列为 missing / out-of-sync / ok。missing 和 out-of-sync 行均违反约定；常规检查会拒绝这些情况。
• 不带参数运行 pnpm run gen-translation-brief，会输出所有不同步配对的简报。
• 在编辑配对文档的 PR 中，工作清单就是差异本身：某个配对中的任何一侧有更改，都需要更新对应的另一侧，并在同一个 PR 中重新记录配对；如果遗漏，检查门禁就会报错。

完成配对

1. 切换链接：在中文文件的 H1 后立即添加 [English](foo.md) | 中文，在英文文件的 H1 后添加 English | [中文](foo.zh.md)。如果这是一个新配对，两边都添加；但生成器拥有的英文源文件应与生成器输出逐字节一致，不添加切换链接，中文对应文件仍需链接回英文文件。
2. 记录一致性：pnpm run verify-translation-pairing --write <pair> 会重新计算并记录 foo.i18n.yaml 中各个部分的哈希值。PR 中的 yaml 差异是可供审查的声明：「我确认这两份内容表达相同意思」——只有在你确实确认之后才运行此命令。
3. 普通文档无需添加清单条目：所有范围内的源文件都必须有对应文件。只有在所属策略文档明确规定存在真正的生成内容、教学内容或按设计双语的排除项时，才修改 scripts/translation-pairing.manifest.json。
4. 提交 PR 前：受影响的配对应通过范围检查；pnpm run doc-sync（其中包含整个语料库的配对检查，以及 verify-md-wrap/verify-md-links）应按 dsh-pre-push-checks 的要求，在 PR 级别运行一次，而不是在每个翻译任务中运行。
5. 让 PR 易于审查：说明哪些配对是新增的，哪些只是做了最小更新，并醒目列出「待定术语」。

如何回复翻译审查意见

遵循 代码审查报告指南：根据每条意见本身的合理性进行评估；对于术语意见，请记住术语表才是准则——将审查者决定的译法应用到 terminology.md，而不只是修改单个文件。