docs: harden pairing gate per review — structural signature, not counts

Review findings addressed:

- The gate compared only heading and code-block COUNTS, understating the
  contract it claims to enforce. It now compares ordered structural
  signatures: heading depths, fenced code blocks verbatim (info string +
  content), table column counts, list kinds, and every link target except
  the language switcher. Proven red on a heading demotion, a reworded
  code-block comment, and a retargeted link; green on all existing pairs.
- Stated the gate's limit explicitly (header comment + docs/i18n/README.md
  both languages): green means fresh and structurally sound, NOT verified —
  translation quality is the reviewer's half of the contract.
- first-line extraction no longer silently drops the last character of a
  newline-less file (split with limit instead of indexOf slice).
- isExcluded documents the trailing-slash-is-the-boundary invariant.
- Rollout guidance: grow the required frontier at the pace translation
  review is resourced.
- dsh-code-review's doc-sync sublist is now the exhaustive chain.

docs/i18n/README.zh.md updated via the minimal-diff workflow and
re-fingerprinted.
This commit is contained in:
Ziya
2026-07-03 02:06:57 -07:00
parent cd9d559805
commit a899226397
4 changed files with 103 additions and 30 deletions

View File

@@ -1,4 +1,4 @@
<!-- i18n-source: docs/i18n/README.md@e70a1fed0d0e -->
<!-- i18n-source: docs/i18n/README.md@fb0e17390e02 -->
# 双语文档
@@ -18,20 +18,22 @@
用 blob hash 而不是 commit hash,这样同一个 PR 里改动的英文文件也能算出指纹(`git hash-object docs/foo.md`),过期检测则是纯内容比较。指纹同时也是更新工具:`git cat-file -p <hash>` 能还原过期译文当初依据的确切源文本,`git diff <hash> <当前 blob>` 能隔离出变化的部分,让译文做最小更新而不是整篇重译。
- **语言切换行。**两个文件在各自 H1 标题之后立即互链:英文文件带 `English | [中文](foo.zh.md)`,中文文件带 `[English](foo.md) | 中文`。
- **结构与源一一对应。**标题层级、列表形态、表格列与代码块和英文文件一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效(`verify-md-wrap`、`verify-md-links`)。
- **结构与源一一对应。**标题深度与顺序、列表类型、表格列、链接目标与逐字节一致的代码块和英文文件一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效(`verify-md-wrap`、`verify-md-links`)。
## 门禁:verify-translation-pairing
`pnpm run verify-translation-pairing`(`doc-sync` 的一环,因此 CI 和 pre-push 钩子都会运行)机械地强制这份契约:
1. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个英文文件都有 `.zh.md` 配对文件。
2. 每个已存在的 `.zh.md` 文件——无论是否 required——都通过全部检查:其英文源存在(无孤儿)、指纹等于源的当前 blob hash(无过期译文)、双方都带语言切换行、其代码块与标题数量等于源文件。
2. 每个已存在的 `.zh.md` 文件——无论是否 required——都通过全部检查:其英文源存在(无孤儿)、指纹等于源的当前 blob hash(无过期译文)、双方都带语言切换行、其结构签名与源按序一致——标题深度、逐字节一致的代码块(信息串与内容)、表格列数、列表类型、以及除切换行之外的每个链接目标。
3. 列为 `excluded` 的文件完全没有 `.zh.md` 配对。
`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前翻译状态——missing、stale 或 ok——是翻译批次的工作清单。它从不失败;它只报告。
这个门禁带来的实际规则是:**当一个 PR 修改了已有 `.zh.md` 配对的英文文档时,同一个 PR 更新译文**(运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill),与本仓库既有的代码/README doc-sync 规则完全一致。留下过期译文的 PR 会在 CI 变红。
把门禁的边界说白:**门禁绿意味着新鲜且结构健全,不意味着已核验。**它检查指纹和形状;它无法判断中文是否准确、术语是否得当、行文是否自然——那是契约中评审者的那一半,见 [translation-rules.md](translation-rules.md)。一个重打了指纹但翻得潦草的 `.zh.md` 能通过门禁;它不应通过评审。
## 范围、排除与推进
**范围**:根 `README.md` 与 `docs/**` 下的全部内容。package README(`packages/**`)在后续批次加入范围。
@@ -42,7 +44,7 @@
- `docs/AGENTS.md` —— agent 指令,与根 `AGENTS.md` 一样只以英文维护。
- `docs/i18n/terminology.md` —— 术语表本身即是双语构造。
**推进**:manifest 中的 `required` 列表是强制边界,不是目标。目标是范围内的全量双语覆盖。翻译按可评审的批次落地(核心入口文档、cookbook、RFC、postmortem……);每个批次合入后把其文件加进 `required`,门禁只进不退。尚未进入 `required` 的文档是 backlog——在 `--list` 中可见——但任何已存在的译文无论在不在清单里都按完整契约检查。
**推进**:manifest 中的 `required` 列表是强制边界,不是目标。目标是范围内的全量双语覆盖。翻译按可评审的批次落地(核心入口文档、cookbook、RFC、postmortem……);每个批次合入后把其文件加进 `required`,门禁只进不退。尚未进入 `required` 的文档是 backlog——在 `--list` 中可见——但任何已存在的译文无论在不在清单里都按完整契约检查。给一篇文档配对是一份承诺:此后对它的每次英文修改都必须带上译文,所以边界的扩张要跟上翻译评审的实际投入节奏,不要抢在前面。
## 分工