translate-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Translating documentation

文档翻译

Invocation boundary

调用边界

Run this workflow when the task is explicitly about maintaining bilingual pairs — a whole-document translation, a batch of new counterparts, or a requested pairing audit. It is model- and user-reachable on purpose, because the

ask-demon

cascade fires it after an earlier flow step touched docs or notes. Routine counterpart updates for a small prose change are made directly in one pass after loading the repository's terminology table; they do not need this skill.

当任务明确涉及维护双语文档对时运行此工作流——包括整文档翻译、批量生成新对应文档，或按需进行文档配对审核。本工作流可由模型和用户触发，因为在早期流程步骤涉及文档或笔记后，

ask-demon

级联会触发它。针对小篇幅文本修改的常规对应文档更新，可在加载仓库术语表后直接一次性完成；无需使用此技能。

What this skill is

本技能说明

This skill is guidance, not a translation memory. Both languages carry equal authority — a change is authored in either one, and that side is the source for that update. The rules below say what must hold, not how to phrase any sentence; phrasing judgment is yours, terminology is not.

**本技能是操作指南，而非翻译记忆库。**两种语言具有同等权威性——修改可在任意一侧发起，该侧即为本次更新的源端。以下规则规定了必须遵循的要求，而非具体语句的措辞方式；措辞判断由你决定，但术语使用必须严格遵守规定。

Triage by change type

按变更类型分类处理

Update (pair exists, one side edited): follow the update path. It is briefing-driven and deliberately cheap: no guidance-corpus re-reading, no git archaeology, smallest counterpart edit. Never re-translate a whole document to apply an update — a minimal update preserves the reviewed phrasing of everything that did not change.
New pair (no counterpart yet): follow the whole-document path.
Deleted or renamed doc: delete or rename the counterpart and the
```
.i18n.yaml
```
consistency record alongside it — the pairing gate reports an incomplete pair otherwise.

Frozen archived notes are not translation work; never update either side after archival.

更新（文档对已存在，其中一侧已编辑）：遵循更新流程。该流程基于简报驱动，且刻意简化：无需重新阅读指导语库、无需进行Git溯源，仅需对对应文档做最小修改。绝不要为了应用更新而重新翻译整个文档——最小化更新可保留所有未变更内容的已审核措辞。
新建文档对（尚无对应文档）：遵循整文档流程。
文档删除或重命名：删除或重命名对应文档及配套的
```
.i18n.yaml
```
一致性记录——否则配对检查器会报告文档对不完整。

已归档的冻结笔记无需进行翻译工作；归档后绝不要更新任意一侧的内容。

The update path (briefing-driven)

更新流程（基于简报驱动）

Generate the briefing. Run the repository's translation-brief script for the pair when it has one (no arguments briefs every out-of-sync pair); without one, derive the changed units by diffing the edited side against the last-confirmed counterpart. The briefing maps the change at the narrowest safely aligned granularity — changed Markdown units (paragraph, table row, list item, heading), then whole heading sections, then whole document — and carries each changed unit's last-confirmed source, current source, and current counterpart text, plus the terminology rows the change touches.
Mechanical-only diff? Apply it. When every change lies inside code fences the pair shares byte-identically, the repository's translation-brief script, when present, with its apply flag splices the edited fences into the counterpart and structure-validates the result before writing — no subagent, no hand-editing.
Prose diff? Delegate to a subagent, passing the briefing (or the command to generate it). The briefing is the translator's whole working set — the subagent does not re-read the guidance corpus or re-derive the diff. It escalates to the whole-document path's sources of truth only when the briefing leaves a decision genuinely unanswerable — an unlisted term with no precedent nearby, or a whole-document briefing, which always means reconciling by hand under the repository's translation rules.
Smallest edit that covers the diff. Preserve the reviewed phrasing of everything the diff does not touch, then verify the changed hunks clause by clause against the source: nothing added, nothing dropped, terminology per the table, code spans verbatim.
Record and verify, scoped. Re-record the pair with the pairing gate's
```
--write <pair>
```
flag, then run the scoped check on that pair. The corpus-wide check still runs in the repository's documentation gates; do not run it per update.

生成简报：若仓库配有翻译简报脚本，针对目标文档对运行该脚本（无参数时会为所有不同步的文档对生成简报）；若无该脚本，则通过对比编辑后的文档与最后一次确认的对应文档，推导变更单元。简报会以最窄且安全对齐的粒度映射变更——变更的Markdown单元（段落、表格行、列表项、标题），然后是整个标题章节，最后是整个文档——并包含每个变更单元的最后一次确认源文本、当前源文本、当前对应文档文本，以及变更涉及的术语条目。
仅为代码块差异？直接应用：当所有变更都位于文档对完全相同的代码块内时，若仓库配有翻译简报脚本，使用其应用标志可将编辑后的代码块插入对应文档，并在写入前验证结构有效性——无需子代理，无需手动编辑。
文本差异？委托子代理处理，并传递简报（或生成简报的命令）。简报是译者的全部工作集——子代理无需重新阅读指导语库或重新推导差异。仅当简报无法真正回答决策问题时，才会升级到整文档流程的可信源——比如未列出且附近无先例的术语，或整文档简报（这通常意味着需根据仓库翻译规则手动协调）。
最小化修改以覆盖差异：保留差异未涉及的所有已审核措辞，然后逐句验证变更部分与源文本的一致性：无新增内容、无遗漏内容、术语符合术语表、代码段完全一致。
记录并验证（限定范围）：使用配对检查器的
```
--write <pair>
```
标志重新记录文档对，然后对该文档对运行限定范围的检查。语库级检查仍会在仓库的文档检查器中运行；无需在每次更新时运行。

The whole-document path (new pairs)

整文档流程（新建文档对）

When translations need to be written from scratch, the orchestrating agent does not translate: spawn a subagent to do the translation work. The translator reads the sources of truth below first, then translates the whole file into the other language — section by section for long documents, keeping each section's structure locked to the source as you go.

当需要从头开始翻译时，编排代理不负责翻译：需生成子代理来完成翻译工作。译者需先阅读以下可信源，再将整个文件翻译成另一种语言——长文档可逐节翻译，翻译过程中保持每节结构与源文档一致。

Sources of truth (read, don't re-summarize)

可信源（阅读即可，无需重新总结）

The repository's pairing contract — the pairing rules, switchers, the
```
.i18n.yaml
```
consistency record's both-side blob hashes, scope, and exclusions.
The repository's translation rules — faithfulness, structure preservation, terminology discipline, typography, and the MUST/SHOULD levels.
The repository's terminology table — binding in both directions. Load it before translating, not when a term feels uncertain; the terms you don't notice are the ones that drift.
```
prose-standard
```
— required prose coverage and editorial judgment. Apply it to both sides without adding or dropping source propositions.

仓库的配对协议——配对规则、切换器、
```
.i18n.yaml
```
一致性记录中的双方Blob哈希、范围及排除项。
仓库的翻译规则——忠实性、结构保留、术语规范、排版，以及MUST/SHOULD级别要求。
仓库的术语表——双向绑定。翻译前加载术语表，不要等到对术语存疑时才加载；容易被忽略的术语正是会出现偏差的术语。
```
prose-standard
```
——要求的文本覆盖范围和编辑判断。需对双方应用该标准，不得添加或遗漏源文档的命题。

Translate

翻译步骤

Pass 1 — write, don't transpose. Read a semantic unit, then restate it as a native technical author in the register of the nearest style sample the repository keeps. Preserve the required frame without forcing sentence-by-sentence correspondence.
Pass 2 — verify against the source, clause by clause. Confirm nothing was added or dropped, every term follows the table, and each code span survived verbatim. Fix by rewriting the sentence natively, not by patching words in.
Read the completed counterpart alone and rewrite phrasing whose awkwardness only shows in isolation. Write only the final text, never drafts.
Every term in the terminology table renders exactly as listed. An unlisted term needs a citable precedent or stays English with a short gloss; never invent a rendering inline.
Code blocks are byte-identical across the pair, comments included. Relative links keep their
```
.md
```
targets; only the switcher line links
```
.zh.md
```
.
The pairing gate checks heading depths, fenced blocks, table row and column counts, list kinds and starts, list item counts, and link targets. In Pass 2, manually verify list and table order, noncanonical list numbering, inline code, emphasis, meaning, terminology, and tone.

第一遍——撰写，而非逐句转换：读取一个语义单元，然后以母语技术作者的身份，按照仓库中最接近的风格样本重新表述。保留所需框架，无需强制逐句对应。
第二遍——逐句对照源文档验证：确认无新增或遗漏内容、所有术语符合术语表、每个代码段完全一致。通过重新撰写句子（符合母语表达）来修正问题，而非逐词修改。
单独阅读完成的对应文档，并重写仅在单独阅读时才显露出的生硬措辞。仅撰写最终文本，不要保留草稿。
术语表中的每个术语必须完全按照列表呈现。未列出的术语需有可引用的先例，或保留英文并附上简短注释；绝不要在翻译时自行创造译法。
代码块在文档对中必须完全相同（包括注释）。相对链接保留其
```
.md
```
目标；仅切换器行链接
```
.zh.md
```
。
配对检查器会检查标题层级、代码块、表格行列数、列表类型及起始值、列表项数量，以及链接目标。在第二遍验证时，需手动检查列表和表格顺序、非标准列表编号、内联代码、强调内容、含义、术语和语气。

Find the work

查找待处理工作

The pairing gate with
```
--list
```
prints every in-scope document as missing / out-of-sync / ok. Missing and out-of-sync rows are contract violations; the normal check rejects them.
The repository's translation-brief script, when present, run with no arguments prints the briefing for every out-of-sync pair.
In a change that edits paired docs, the work list is the diff itself: every changed side of a pair needs its counterpart updated and the pair re-recorded in the same change, and the gate goes red if you forget.

使用
```
--list
```
参数运行配对检查器，会打印所有范围内文档的状态：缺失/不同步/正常。缺失和不同步的行属于协议违规；常规检查会拒绝这些情况。
若仓库配有翻译简报脚本，无参数运行该脚本会为所有不同步的文档对生成简报。
在涉及编辑配对文档的变更中，工作清单即为差异本身：文档对中每一个被编辑的侧都需要更新其对应文档，并在同一变更中重新记录文档对；若遗漏，检查器会标记为错误。

Finish the pair

完成文档对

Switcher:
```
English | [中文](foo.zh.md)
```
after the English H1,
```
[English](foo.md) | 中文
```
after the Chinese H1 — add both for a new pair. Instruction files named
```
AGENTS.md
```
and
```
SKILL.md
```
never get a counterpart.
Record consistency: the pairing gate's
```
--write <pair>
```
flag recomputes and records both sides' blob hashes in the
```
.i18n.yaml
```
consistency record. The record's diff is the reviewable statement "I confirmed these two say the same thing" — run it only after you actually have.
No manifest entry is needed for an ordinary document: every in-scope source requires a pair. Change the repository's pairing manifest only when the owning policy documents a genuine generated, instructional, or bilingual-by-construction exclusion.
Before the change: the touched pairs are green under the scoped check; the repository's documentation gates (which include the corpus-wide pairing check plus wrap and link checks) run once per change, not inside each translation task.
Keep the change reviewable: state which pairs are new versus minimally updated and list any unlisted terms prominently.

切换器：英文H1标题后添加
```
English | [中文](foo.zh.md)
```
，中文H1标题后添加
```
[English](foo.md) | 中文
```
——新建文档对时需添加两者。名为
```
AGENTS.md
```
和
```
SKILL.md
```
的说明文档无需生成对应文档。
记录一致性：使用配对检查器的
```
--write <pair>
```
标志重新计算并记录双方的Blob哈希到
```
.i18n.yaml
```
一致性记录中。该记录的差异是可审核的声明“我确认这两份文档内容一致”——仅在实际确认后再运行该命令。
普通文档无需在清单中录入：所有范围内的源文档都需要对应文档。仅当所属策略明确记录了真正的生成文档、说明文档或天生双语文档的排除项时，才修改仓库的配对清单。
变更前：受影响的文档对在限定范围检查中显示为正常；仓库的文档检查器（包括语库级配对检查、换行和链接检查）会在每次变更时运行一次，而非在每个翻译任务内运行。
保持变更可审核：说明哪些文档对是新建的、哪些是最小化更新的，并突出列出所有未在术语表中收录的术语。

How to respond to translation review

如何回应翻译审核

Follow the review reporting guidance in

repo-standards-review

: evaluate each comment on its merits. For terminology comments, the terminology table is the contract — apply a reviewer's rendering decision to the terminology table, not only to one file.

遵循

repo-standards-review

中的审核报告指南：根据实际情况评估每条评论。对于术语相关的评论，术语表是协议依据——需将审核者的译法决策应用到术语表中，而非仅修改单个文件。