mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00

Files

Ziya ec05295a0c docs: equal-authority pairing with sidecar consistency records

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

2026-07-03 07:41:24 -07:00

5.4 KiB

Raw Blame History

name, description

name	description
dsh-translate-docs	Use when creating or updating the bilingual counterpart of a doc in this repo (English ↔ Chinese pairs) — orients the translator to the pairing contract, the terminology source of truth, the translation rules, and the consistency gate that verifies the result

Translating DeepSeek-Harness docs

This skill is guidance, not a translation memory. It is the workflow map for keeping foo.md ↔ foo.zh.md pairs consistent and natural in both languages. Both languages carry equal authority — a change is authored in either one, and that side is the source for that update. You are the translator: the rules below say what must hold, not how to phrase any particular sentence — phrasing judgment is yours, terminology is not.

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

These are authoritative; read them at the source so this skill never drifts out of sync.

docs/i18n/README.md — the pairing contract: the three-file pair (foo.md, foo.zh.md, foo.i18n.yaml), the consistency record's both-side blob hashes, the language-switcher lines, scope/exclusions, and the rollout manifest.
docs/i18n/translation-rules.md — how to translate: faithfulness, structure preservation, terminology discipline, typography (MUST/SHOULD levels).
docs/i18n/terminology.md — the 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.

Find the work

pnpm run verify-translation-pairing --list prints every in-scope document as missing / out-of-sync / ok — the work list for a translation batch.
In a PR 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 PR, and the gate goes red if you forget.

Triage by change type

Do not process every file the same way:

New pair (no counterpart yet): whichever language exists — English or Chinese — translate the whole file into the other, section by section for long documents, keeping each section's structure locked to the source as you go rather than fixing structure at the end.
Update (pair exists, one side edited): do NOT re-translate. The consistency record names the exact last-confirmed text of both sides — recover the edited side's previous state and diff:
```
git cat-file -p <hash-from-i18n-yaml> > /tmp/last-confirmed.md
git diff --no-index /tmp/last-confirmed.md docs/foo.md
```
Apply the smallest counterpart edits that cover that diff. A minimal update preserves the reviewed phrasing of everything that didn't change; a re-translation throws that review away.
Deleted or renamed doc: delete or rename the counterpart and the .i18n.yaml alongside it — the gate reports an incomplete pair otherwise.

Translate

Work through the document applying translation-rules.md. Internally: first render faithfully, then re-read the counterpart alone for awkward or ambiguous phrasing, then polish — but write ONLY the final text to the file, never drafts or notes.
Every term in terminology.md renders exactly as specified, in both directions, including first-occurrence annotations. A term the table misses: translate only with a citable precedent from a major Chinese OSS/vendor doc; otherwise keep the English and add it to the PR's 「待定术语」 list with your suggested rendering. Never invent a rendering inline — that decision belongs to a human and then to the table.
Code blocks are byte-identical across the pair, comments included. Relative links keep their .md targets; only the switcher line links .zh.md.

Finish the pair

Switcher: [English](foo.md) | 中文 immediately after the Chinese file's H1, English | [中文](foo.zh.md) after the English file's H1 — add both if this is a new pair.
Record consistency: pnpm run verify-translation-pairing --write recomputes and records both sides' full blob hashes in foo.i18n.yaml. The yaml diff in your PR is the reviewable statement "I confirmed these two say the same thing" — only run it after you actually have.
New batch landed? Add the .md paths to required in scripts/translation-pairing.manifest.json so the gate ratchets forward.

Verify — the gate, not your eyes

Run pnpm run verify-translation-pairing, then the rest of the Markdown gates (pnpm run verify-md-wrap && pnpm run verify-md-links, or full pnpm run doc-sync before the PR). Fix what they report; do not hand-check what they cover. What they can NOT check — whether the two sides truly say the same thing, terminology judgment calls, tone — is exactly what the PR reviewer will read for, so keep the PR reviewable: state which pairs are new vs minimally updated, and list 「待定术语」 prominently.

How to respond to translation review

Same discipline as any review in this repo (see dsh-code-review § How to respond): evaluate each comment on its merits, and for terminology comments, remember the table is the contract — a reviewer's rendering decision gets applied to terminology.md so it binds every future translation, not just patched into one file.

5.4 KiB Raw Blame History