dshDeepSeek Harness DocsDeepSeek Harness 文档

Translation rules

How to translate between the two sides of a documentation pair in this repo. Both languages carry equal authority (README.md): a change is authored in either language, and that side is the source for that update — these rules govern producing or updating the counterpart. They bind humans and agents equally. Routine agent work translates the changed content directly in one terminology-guided pass; the extended .agents/skills/dsh-translate-docs workflow runs only when the user explicitly invokes it. Rule levels follow RFC 2119 usage: MUST / MUST NOT are gate- or review-blocking; SHOULD needs a stated reason to deviate; MAY is discretionary.

Faithfulness

  • The counterpart MUST say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.
  • The counterpart SHOULD read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.
  • Do not translate the untranslatable: if a sentence resists natural rendering because it leans on an idiom of the source language, translate the idea, not the idiom.

Voice

  • The register is calibrated by style-samples.md — human-approved gold pairs, one per document genre. The counterpart MUST match the target-language side of the nearest sample; where its voice and a prose voice rule disagree, the sample wins. Chinese targets use institutional technical Chinese; English targets use concise professional developer prose.
  • Write as a native technical author restating the content, not as a translator transposing sentences, while preserving every source clause: nothing added, nothing dropped — fluency never justifies losing a clause.
  • Give sentences an explicit actor when the target language would otherwise obscure it; for Chinese, replace vague passives or abstract subjects with the actual actor (系统、门禁、评审人).
  • Prefer established target-language engineering idiom over calques (误报／漏检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack noun chains where the target language requires it.
  • Split long paragraphs by semantic unit — one idea per paragraph. Paragraph boundaries MAY differ from the source; the structural signature does not count paragraphs.
  • When translating into Chinese, category nouns use Chinese with a first-mention English annotation (实操手册（cookbook）); when translating into English, use the conventional English category name. Literal directory or file references stay code-formatted English.

Structure preservation

The pairing gate checks heading depths, fenced code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:

  • heading hierarchy (same levels, same order — heading TEXT is translated),
  • list shape and numbering,
  • tables (same columns, same row order; header cells translated per terminology),
  • fenced code blocks — byte-identical, including comments; the pairing signature compares their info strings and contents, and ```ts blocks compile under doc-typecheck,
  • inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,
  • links and anchors: every relative link MUST point at the same target in both files — by convention the .md path, not the .zh.md sibling — so links never dangle when one pair lands before its neighbors. The ONLY zh-specific link is the language switcher. A README rendered outside GitHub MAY use the canonical public repository URL to its exact counterpart as documented in README.md. Link TEXT is translated; the target is not.

The repo's Markdown conventions apply to .zh.md files unchanged: one physical line per paragraph (verify-md-wrap), resolving relative links (verify-md-links), exactly one trailing newline.

Terminology

  • terminology.md is the source of truth in both directions. Before translating, load it; every listed term MUST follow its row and its "不要译作" prohibitions. A Chinese target uses the "中文" column and its "首次出现" annotation; an English target uses the "English" column without adding a Chinese gloss.
  • For a Chinese target, an unlisted technical term MAY use an established rendering from a major Chinese-language OSS or vendor source (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs), cited in the PR. Without such precedent it MUST stay in English and be listed under 「待定术语」(pending terms) with a suggested rendering.
  • For an English target, use the established English technical term. If the source term has no unambiguous established equivalent, preserve it with a short explanatory gloss and list it under pending terms. Neither direction may invent a rendering inline; a decided term enters terminology.md in the same PR or a follow-up.

Typography

These rules govern the Chinese side; the English side follows the repo's normal Markdown conventions (root AGENTS.md). The mixed-script rules below follow the cross-project consensus of the MDN Simplified Chinese translation guide, the Kubernetes zh-cn localization guide, the Vue.js Chinese translation conventions, and 中文文案排版指北, which in turn ground in W3C clreq and GB/T 15834—2011:

  • MUST put one half-width space between Chinese text and Latin words, and between Chinese text and numerals: 每个 plugin 注册 3 个 tool。No space between a full-width punctuation mark and anything.
  • MUST use full-width (Chinese) punctuation in Chinese prose: ，。：；？！（）「」. Half-width punctuation stays inside code spans, inside complete English sentences quoted as-is, and in numbers (3.5, 1,024).
  • Chinese prose SHOULD prefer colons, periods, commas, or parentheses over em dashes. Keep an em dash only when no other punctuation preserves the sentence naturally.
  • Enumeration commas: a Chinese list of parallel items uses 顿号（、）, not commas.
  • MUST NOT use full-width digits or full-width Latin letters — １２３ never, 123 always.
  • Proper nouns keep their canonical casing: GitHub, TypeScript, DeepSeek — never github/Github unless quoting code.
  • Second person is 你, not 您 (matches the Vue and Kubernetes Chinese conventions and this repo's direct voice).
  • Emphasis markers (**bold**, *italic*) stay on the same spans as the source; Chinese has no italics, so the rendered emphasis may look identical — do not substitute quotation marks or other decoration.

Quality bar

  • A pair is done when a bilingual engineer reading either file alone gets everything a reader of the other gets — same facts, same caveats, same tone — and nothing extra.
  • Run pnpm run verify-translation-pairing and the rest of doc-sync for records, switchers, heading depths, code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, links, and repository Markdown rules. Human review owns list and table order, noncanonical list numbering, inline code, emphasis, meaning, terminology, and tone.

References

Authorities cited by these rules, for humans and agents who want the underlying reasoning:

  • 中文文案排版指北 — the de-facto community standard for mixed CJK/Latin spacing and punctuation.
  • MDN zh-CN translation guide — an in-repo translation-rules file of the same shape as this one; spacing, punctuation, and glossary practice.
  • Kubernetes zh-cn localization guide — terminology-first-occurrence and punctuation practice from the largest zh localization team.
  • Vue.js docs-zh-cn 翻译须知 — per-term translate/keep decisions and tone.
  • zh-style-guide — a community Chinese technical-writing style guide whose rule-level taxonomy (and RFC 2119 keyword levels) this file borrows; aggregates GB/T 15834/15835, clreq, and vendor guides.
  • W3C clreq and the Microsoft Simplified Chinese style guide — the formal typographic and vendor-localization baselines.
  • GB/T 19682-2005《翻译服务译文质量要求》 — the national standard whose three base requirements (忠实原文、术语统一、行文通顺) this file's Faithfulness and Terminology sections operationalize.

翻译规则

本文规定：如何在本仓库文档配对的中英文两种语言之间进行翻译。两种语言同权（见 README.md）：每次变更可以用任一语言撰写，被编辑的一侧即为本次更新的源；本文的规则约束如何产出或更新对侧文件。这些规则对人类和 agent（智能体）同等生效。日常工作中，agent 会在术语指导下直接一次完成有改动内容的翻译；扩展版 .agents/skills/dsh-translate-docs 工作流仅在用户显式调用时运行。规则级别沿用 RFC 2119 的用法：必须（MUST） ／ 禁止（MUST NOT） 会卡门禁或评审；应当（SHOULD） 偏离时要说明理由；可以（MAY） 自行裁量。

忠实性

  • 对侧文件必须传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。
  • 对侧文件读起来应当是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。
  • 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。

行文

  • 语体以 style-samples.md 为校准锚点。人工定稿的金标样例按文体各一组，译文必须参照文体最接近的样例，采用其中目标语言一侧的语体；如果样例与本文的行文规则冲突，以样例为准。译成中文时，采用规范的技术制度文；译成英文时，采用简洁、专业的开发者文档语体。
  • 以母语技术作者的身份重述内容，而不是以译者身份逐句转写，同时保留原文的每个语义成分：不添加、不遗漏——流畅永远不是丢掉语义成分的理由。
  • 如果直译会让执行主体含糊，请明确写出实际执行者；译成中文时，应由「系统、门禁、评审人」等实际执行者作主语，避免含糊的被动句或抽象主语。
  • 优先采用目标语言中通行的工程表达，避免生硬直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻应自然改写，名词链则按目标语言的习惯拆开。
  • 长段按语义单元拆分，一段一件事。段落边界可以与原文不同；结构签名不比对段落数。
  • 翻译为中文时，类别名词使用中文并在首现括注英文（实操手册（cookbook））；翻译为英文时，使用通行的英文类别名。指目录或文件本身时保留代码体英文。

结构保持

配对门禁会检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起始编号、列表项数量与链接目标；门禁未覆盖的结构仍需人工核对。两个配对文件必须在以下方面一一对应：

  • 标题层级（相同级别、相同顺序；标题的文字要翻译）；
  • 列表形态与编号；
  • 表格（相同的列、相同的行序；表头单元格按术语表翻译）；
  • 围栏代码块：逐字节一致，包括注释。配对签名比对信息字符串与内容，```ts 块还要通过 doc-typecheck 编译；
  • 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；
  • 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 .md 路径而非 .zh.md 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。在 GitHub 以外位置渲染的 README 可以按 README.md 的规定，使用指向确切对侧文件的规范公开仓库 URL。链接文字翻译；链接目标不翻。

本仓库的 Markdown 约定对 .zh.md 文件原样生效：一个段落一个物理行（verify-md-wrap）、相对链接必须可解析（verify-md-links）、文件末尾恰好一个换行。

术语

  • terminology.md 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。译成中文时，采用「中文」列，并按「首次出现」列括注；译成英文时，采用「English」列，不加中文括注。
  • 译成中文时，术语表未收录的技术术语只有在主流中文 OSS 文档或厂商资料中已有通行译法时才可以翻译（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档），并须在 PR 中注明出处；否则必须保留英文，并在 PR 描述的「待定术语」中给出建议译法。
  • 译成英文时，采用通行的英文技术术语。如果源术语没有明确的通行对应词，则保留原词、附上简短说明，并列入「待定术语」。两个方向都不得自行创造译法；确定后的术语须在同一个 PR 或后续 PR 中加入 terminology.md。

排版

本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 AGENTS.md）。以下中西文混排规则遵循 MDN 简体中文翻译指南、Kubernetes 中文本地化指南、Vue.js 中文翻译须知 与中文文案排版指北的跨项目共识，其根据是 W3C clreq 与 GB/T 15834—2011：

  • 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：每个 plugin 注册 3 个 tool。全角标点与任何字符之间不加空格。
  • 中文行文必须使用全角（中文）标点：，。：；？！（）「」。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（3.5、1,024）。
  • 中文行文应当优先使用冒号、句号、逗号或括号，尽量不用破折号；只有其他标点都无法自然表达时才保留破折号。
  • 顿号：中文的并列项之间使用顿号（、），而非逗号。
  • 禁止使用全角数字或全角拉丁字母：永远不写 １２３，永远写 123。
  • 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek。除非引用代码，否则绝不写 github／Github。
  • 第二人称用「你」，不用「您」（与 Vue、Kubernetes 中文约定及本仓库的直接语气一致）。
  • 强调标记（**加粗**、*斜体*）落在与对侧相同的文字段上。中文没有斜体，渲染效果可能看不出差别，不要用引号或其他装饰替代。

质量标准

  • 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。
  • 请运行 pnpm run verify-translation-pairing 与 doc-sync 的其余门禁。这些门禁会检查一致性记录、切换行、标题深度、代码块、表格行列数、列表类型、有序列表起始编号、列表项数量、链接及仓库 Markdown 规则；列表与表格的顺序、非常规列表编号、行内代码、强调标记、语义、术语和语体则由人工评审负责。

参考资料

本文各规则引用的权威出处，供想了解底层依据的人和 agent 查阅：

  • 中文文案排版指北：中西文混排空格与标点的社区事实标准。
  • MDN 简体中文翻译指南：与本文同形态的仓库内置翻译规则文件；空格、标点与术语表实践。
  • Kubernetes 中文本地化指南：最大的中文本地化团队的术语首现与标点实践。
  • Vue.js docs-zh-cn 翻译须知：逐术语的译／留决策与语气。
  • zh-style-guide：社区中文技术文档写作规范，本文借用了它的规则级别分类体系（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。
  • W3C clreq 与微软简体中文风格指南：排版学与厂商本地化的正式基线。
  • GB/T 19682-2005《翻译服务译文质量要求》：国家标准；本文「忠实性」与「术语」两节将其三项基本要求（忠实原文、术语统一、行文通顺）落实为可操作的规则。