Redesign per review: neither language is canonical. A pair is three
sibling files — foo.md, foo.zh.md, foo.i18n.yaml — and either language
may be authored first (a Chinese-first RFC is as legitimate as an
English-first one). The sidecar record holds the FULL git blob hash of
both sides as of the last confirmed-consistent state, replacing the
in-file one-directional fingerprint; editing either side without
re-confirming the pair goes red. New --write mode re-records a pair
after both sides are brought in line, making the confirmation a
reviewable yaml diff. Pairs merge whole (completeness enforced).
- gate rewritten around pair anchors (union of .zh.md and .i18n.yaml
remnants) so half-deleted pairs are caught from either side; red/green
proven for en-only edit, zh-only edit, missing record, and a record
for an excluded file
- verify-rfc-classification now skips .zh.md counterparts (same RFC,
indexed via its English filename; the pairing gate owns consistency)
- docs/i18n/README.md + translation-rules.md reframed bidirectionally
(terminology table binds both directions; typography section governs
the Chinese side); zh counterparts updated; skill workflow updated
- RFC amended to the shipped design, records the English-canonical
in-file-fingerprint model as considered-and-revised; RFC translated
(docs/rfc/.../2026-07-02-bilingual-docs-and-pairing-gate.zh.md) and
added to the required frontier
- generated docs stay excluded with the follow-up recorded: teach the
generators to emit Chinese, then de-list
A four-way parallel review of every EN<->ZH pair (one reviewer per pair,
findings verified before applying) surfaced:
- terminology: stale-sense 过期 -> 陈旧 in development.zh.md (the table
reserves 过期 for expired); GitHub workflow -> GitHub 工作流 per the
table; dropped the invented 质量 in 'CI gates' -> CI 门禁; taxonomy ->
分类体系 in translation-rules.zh.md; skill first-occurrence annotation
added in the i18n README
- verbatim spans: <current-blob> restored inside an inline code span the
translation had localized
- typography: full-width dashes normalized to no surrounding spaces
across all four files (the rules' own MUST); one 顿号 between clauses
-> comma; 顿号 before 以及 dropped
- fidelity/wording: must-not rendered 不得 (not 不应); local setup ->
本地环境搭建; enforce -> 强制执行; verified surface -> 受验证的范围;
batch-lands-before-neighbors nuance restored; 更新粘贴内容
freshness -> 新鲜度 confirmed against MDN's zh HTTP caching docs (freshness
lifetime -> 新鲜度生命周期); precedent now cited in the table. The same
source pairs stale with 陈旧, not 过期 (过期 maps to expired), so the stale
entry and the i18n README translation now say 陈旧译文.
Every new term the bilingual-docs work introduced, with precedented
renderings where precedent exists:
- orphan -> 孤立 (git's official zh l10n renders orphan as 孤立, e.g.
孤立分支 — not 孤儿; the translations were corrected to match)
- info string -> 信息字符串 (CommonMark zh convention; corrected in the
i18n README translation)
- fenced code block -> 围栏代码块 (MDN zh), staged -> 暂存 (git zh),
event-sourced -> 事件溯源 (DDD convention), smoke test -> 冒烟测试,
fail-fast -> 快速失败, plus fingerprint/pairing/freshness/stale/contract
- mechanism names coined by this repo, marked as such in the notes:
language switcher -> 语言切换行, structural signature -> 结构签名,
enforcement frontier -> 强制边界
- keep-English entries so future translators don't guess: backlog,
blob hash, CI, doc-sync, e2e, monorepo, PR, worktree
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.
Establish EN->ZH bilingual documentation for the README and docs tree:
- docs/i18n/README.md — the pairing contract: sibling foo.md <-> foo.zh.md,
English canonical, blob-hash source fingerprints, language switchers,
scope/exclusions, and a manifest-driven rollout ratchet.
- docs/i18n/translation-rules.md — how to translate: faithfulness, structure
preservation, terminology discipline over docs/i18n/terminology.md, and
typography rules grounded in MDN/K8s/Vue/clreq conventions.
- .agents/skills/dsh-translate-docs — the committed agent workflow, following
the dsh-code-review pattern of deferring to docs as sources of truth.
- scripts/verify-translation-pairing.ts + manifest — a doc-sync gate: required
pairs exist; every existing .zh.md is fresh (fingerprint = current source
blob), switcher-linked, structure-matched, and non-orphaned; excluded
(generated) docs stay unpaired. --list prints the translation work list.
- RFC (implemented/process) recording the decision and the alternatives.
- Dogfood: README.zh.md and the two i18n docs translated under their own rules.
Gates: doc-sync green including the new gate; red/green proven for stale
fingerprint, orphan, and excluded-file violations.
