From bb10931478f36107782a48da9287c1eb6616542f Mon Sep 17 00:00:00 2001 From: Ziya <199893125+ZiyaZhang@users.noreply.github.com> Date: Fri, 3 Jul 2026 02:53:08 -0700 Subject: [PATCH] docs: apply translation-review findings across the four zh files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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: 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; 更新粘贴内容 --- README.zh.md | 2 +- docs/development.zh.md | 14 +++++++------- docs/i18n/README.zh.md | 16 ++++++++-------- docs/i18n/translation-rules.zh.md | 20 ++++++++++---------- 4 files changed, 26 insertions(+), 26 deletions(-) diff --git a/README.zh.md b/README.zh.md index 4c911a42e0..62dbb01683 100644 --- a/README.zh.md +++ b/README.zh.md @@ -21,6 +21,6 @@ pnpm run demo:echo # runnable echo-agent example (no API key needed) pnpm run demo:coding # the real DeepSeek coding agent (needs DEEPSEEK_API_KEY) ``` -面向人类读者：先读[开发指南](docs/development.md)了解本地环境、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。 +面向人类读者：先读[开发指南](docs/development.md)了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。 面向 agent：遵循 [AGENTS.md](AGENTS.md)。 diff --git a/docs/development.zh.md b/docs/development.zh.md index 5f285fbedf..e08980c33d 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -4,7 +4,7 @@ [English](development.md) | 中文 -本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，以及本地钩子、日常检查与 CI 质量门禁的说明。 +本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，并帮助你理解本地钩子、日常检查与 CI 门禁。 ## 前置条件 @@ -67,9 +67,9 @@ vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `v 这些钩子并不与 CI 完全一致。特别是：`pre-push` 跑不带覆盖率的单元测试，而 CI 跑 `pnpm run test:coverage`；CI 还会跑 echo-agent 和 built-bin 冒烟测试，并在 Node 24 和 26 上跑矩阵。 -## CI 质量门禁 +## CI 门禁 -GitHub workflow 在每个 pull request 上运行这些门禁： +GitHub 工作流在每个 pull request 上运行这些门禁： - `pnpm install --frozen-lockfile` - `pnpm run constraints` @@ -136,9 +136,9 @@ pnpm run demo:acp 用三种注释标签之一标记代码中的已知问题，按紧急程度排序： -- `FIXME` —— 应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 `FIXME` 出门。 -- `TODO` —— 应当尽快修复的问题，等资源到位就处理。 -- `XXX` —— 也许某天会修的问题；优先级最低，不作承诺。 +- `FIXME`——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 `FIXME` 出门。 +- `TODO`——应当尽快修复的问题，等资源到位就处理。 +- `XXX`——也许某天会修的问题；优先级最低，不作承诺。 选择与紧急程度匹配的标签，让扫代码的人一眼分清「发布阻塞」和「有空再说」。 @@ -150,7 +150,7 @@ pnpm run demo:acp { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" } ``` -`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明，并断言文档块与之一致（对空白和注释不敏感，因此文档块可以展示干净的定义、语义由行文承载）。它还强制 1:1 对应：每个 `ts type-equiv` 块恰好有一条 manifest 条目，反之亦然，因此不会有块被静默漏检，也不会有过期条目滞留。`doc-typecheck` 跳过 `ts type-equiv` 块（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个被记录的类型，门禁会失败直到你更新粘贴；当你增删一个块，在同一个变更里更新 manifest。 +`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明，并断言文档块与之一致（对空白和注释不敏感，因此文档块可以展示干净的定义，语义由行文承载）。它还强制 1:1 对应：每个 `ts type-equiv` 块恰好有一条 manifest 条目，反之亦然，因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过 `ts type-equiv` 块（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个被记录的类型，门禁会失败直到你更新粘贴内容；当你增删一个块，在同一个变更里更新 manifest。 ## 架构上下文 diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md index f86c2a2512..d7e0b29dc8 100644 --- a/docs/i18n/README.zh.md +++ b/docs/i18n/README.zh.md @@ -16,23 +16,23 @@ ``` - 用 blob hash 而不是 commit hash，这样同一个 PR 里改动的英文文件也能算出指纹（`git hash-object docs/foo.md`），陈旧检测则是纯内容比较。指纹同时也是更新工具：`git cat-file -p ` 能还原陈旧译文当初依据的确切源文本，`git diff <当前 blob>` 能隔离出变化的部分，让译文做最小更新而不是整篇重译。 + 用 blob hash 而不是 commit hash，这样同一个 PR 里改动的英文文件也能算出指纹（`git hash-object docs/foo.md`），陈旧检测则是纯内容比较。指纹同时也是更新工具：`git cat-file -p ` 能还原陈旧译文当初依据的确切源文本，`git diff ` 能隔离出变化的部分，让译文做最小更新而不是整篇重译。 - **语言切换行。**两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。 - **结构与源一一对应。**标题深度与顺序、列表类型、表格列、链接目标与逐字节一致的代码块和英文文件一一对应——完整保持规则见 [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 钩子都会运行）机械地强制这份契约： +`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 变红。 +这个门禁带来的实际规则是：**当一个 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` 能通过门禁；它不应通过评审。 +把门禁的边界说白：**门禁绿意味着新鲜且结构健全，不意味着已核验。**它检查指纹和形状；它无法判断中文是否准确、术语是否得当、行文是否自然——那是契约中评审者的那一半，见 [translation-rules.md](translation-rules.md)。一个重打了指纹但翻得潦草的 `.zh.md` 能通过门禁；它不得通过评审。 ## 范围、排除与推进 @@ -40,9 +40,9 @@ **排除**（永不配对，门禁拒绝为它们建 `.zh.md`）： -- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/module-graph.md` —— 生成文件；生成器只输出英文，译文在每次重新生成时必然陈旧。 -- `docs/AGENTS.md` —— agent 指令，与根 `AGENTS.md` 一样只以英文维护。 -- `docs/i18n/terminology.md` —— 术语表本身即是双语构造。 +- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/module-graph.md`——生成文件；生成器只输出英文，译文在每次重新生成时必然陈旧。 +- `docs/AGENTS.md`——agent 指令，与根 `AGENTS.md` 一样只以英文维护。 +- `docs/i18n/terminology.md`——术语表本身即是双语构造。 **推进**：manifest 中的 `required` 列表是强制边界，不是目标。目标是范围内的全量双语覆盖。翻译按可评审的批次落地（核心入口文档、cookbook、RFC、postmortem……）；每个批次合入后把其文件加进 `required`，门禁只进不退。尚未进入 `required` 的文档是 backlog——在 `--list` 中可见——但任何已存在的译文无论在不在清单里都按完整契约检查。给一篇文档配对是一份承诺：此后对它的每次英文修改都必须带上译文，所以边界的扩张要跟上翻译评审的实际投入节奏，不要抢在前面。 diff --git a/docs/i18n/translation-rules.zh.md b/docs/i18n/translation-rules.zh.md index 96576782e6..b1cf95a3ef 100644 --- a/docs/i18n/translation-rules.zh.md +++ b/docs/i18n/translation-rules.zh.md @@ -4,7 +4,7 @@ [English](translation-rules.md) | 中文 -本文规定如何把本仓库的文档翻译成简体中文。这些规则对人和 agent（智能体）同等生效；应用它们的进仓 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)，配对与新鲜度机制见 [README.md](README.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）**／**禁止（MUST NOT）**会卡门禁或评审；**应当（SHOULD）**偏离时要说明理由；**可以（MAY）**由译者自行裁量。 +本文规定如何把本仓库的文档翻译成简体中文。这些规则对人和 agent（智能体）同等生效；应用它们的进仓 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)，配对与新鲜度机制见 [README.md](README.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）**／**禁止（MUST NOT）**会卡门禁或评审；**应当（SHOULD）**偏离时要说明理由；**可以（MAY）**自行裁量。 ## 忠实性 @@ -19,9 +19,9 @@ - 标题层级（相同级别、相同顺序——标题的**文字**要翻译）， - 列表形态与编号， - 表格（相同的列、相同的行序；表头单元格按术语表翻译）， -- 围栏代码块——**逐字节一致，包括注释**；代码属于被验证的表面（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移， +- 围栏代码块——**逐字节一致，包括注释**；代码属于受验证的范围（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移， - 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）——原样保留，从不翻译或重排， -- 链接与锚点：每个相对链接必须指向与源文相同的目标——即英文正典文件——这样翻译批次先后落地时链接永不悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。 +- 链接与锚点：每个相对链接必须指向与源文相同的目标——即英文正典文件——这样某批译文先于相邻文件落地时，链接也永不悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。 本仓库的 Markdown 约定对 `.zh.md` 文件原样生效：一个段落一个物理行（`verify-md-wrap`）、相对链接必须可解析（`verify-md-links`）、文件末尾恰好一个换行。 @@ -53,10 +53,10 @@ 本文各规则引用的权威出处，供想了解底层依据的人和 agent 查阅： -- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines) —— 中西文混排空格与标点的社区事实标准。 -- [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md) —— 与本文同形态的进仓翻译规则文件；空格、标点与术语表实践。 -- [Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/) —— 最大的中文本地化团队的术语首现与标点实践。 -- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) —— 逐术语的译／留决策与语气。 -- [zh-style-guide](https://zh-style-guide.readthedocs.io) —— 社区中文技术文档写作规范，本文借用了它的规则分类粒度（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。 -- [W3C clreq](https://www.w3.org/TR/clreq/) 与[微软简体中文风格指南](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides) —— 排版学与厂商本地化的正式基线。 -- GB/T 19682-2005《翻译服务译文质量要求》 —— 国家标准；本文「忠实性」与「术语」两节把它的三项基本要求（忠实原文、术语统一、行文通顺）落成可操作规则。 +- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)——中西文混排空格与标点的社区事实标准。 +- [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)——与本文同形态的进仓翻译规则文件；空格、标点与术语表实践。 +- [Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)——最大的中文本地化团队的术语首现与标点实践。 +- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)——逐术语的译／留决策与语气。 +- [zh-style-guide](https://zh-style-guide.readthedocs.io)——社区中文技术文档写作规范，本文借用了它的规则级别分类体系（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。 +- [W3C clreq](https://www.w3.org/TR/clreq/) 与[微软简体中文风格指南](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides)——排版学与厂商本地化的正式基线。 +- GB/T 19682-2005《翻译服务译文质量要求》——国家标准；本文「忠实性」与「术语」两节把它的三项基本要求（忠实原文、术语统一、行文通顺）落成可操作规则。