diff --git a/README.i18n.yaml b/README.i18n.yaml index 0a981d4323..b765b44217 100644 --- a/README.i18n.yaml +++ b/README.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write README.md: 7ddf68bab06ecf891856e6d1393ccdefd9eeba38 -README.zh.md: 59a0419164f2dfee6f66903cc93d7b35da1d9063 +README.zh.md: ad568c808d4c8003a84734bc8035fac9a07d27b4 diff --git a/README.zh.md b/README.zh.md index 59a0419164..ad568c808d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -6,7 +6,7 @@ ## 开发 -本 monorepo 基于 [Cordis](https://github.com/cordiverse/cordis) 框架构建（以源码形式收录在 `vendor/` 下），采用微内核风格：一切皆插件。 +本 monorepo 基于 [Cordis](https://github.com/cordiverse/cordis) 框架构建（以源码形式收录在 `vendor/` 下），采用微内核风格：所有功能都以插件形式提供。 ```sh pnpm install @@ -15,6 +15,6 @@ pnpm run demo:repl # REPL agent demo (needs DEEPSEEK_API_KEY) pnpm run demo:acp # ACP server agent demo (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.i18n.yaml b/docs/development.i18n.yaml index d8f76162db..ac9ee414b1 100644 --- a/docs/development.i18n.yaml +++ b/docs/development.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write development.md: 28babca2b59c844690750d767c242c08c37bf702 -development.zh.md: b34c52cebd3f333b6554ca2b5ebd66463e436572 +development.zh.md: 91b63d7511f856f21162f8ab66eae6e25d925059 diff --git a/docs/development.zh.md b/docs/development.zh.md index b34c52cebd..91b63d7511 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -2,14 +2,14 @@ [English](development.md) | 中文 -本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，并帮助你理解本地钩子、日常检查与 CI 门禁。 +本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，并帮助你了解本地钩子、日常检查与 CI 门禁。 ## 前置条件 -- Node.js 24 或更新版本。仓库声明 `node >=24`；CI 在 Node 24 和 26 上跑矩阵。 -- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中钉住 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，先运行 `corepack enable`。 +- Node.js 24 或更新版本。仓库声明 `node >=24`；CI 在 Node 24 和 26 上运行矩阵测试。 +- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。 - Git。 -- 可选：一个 DeepSeek API key，用于 REPL/ACP agent（智能体）演示和真实 API 的 e2e 测试。 +- 可选：一个 DeepSeek API key，用于 REPL/ACP agent 演示和真实 API 的 e2e 测试。 ## 首次搭建 @@ -19,23 +19,23 @@ pnpm install ``` -安装同时会运行根目录的 `postinstall` 脚本，它通过 `scripts/install-lefthook.mjs` 从仓库 dev 依赖安装 lefthook；该包装脚本使用 lefthook 经过评审的 `--force` 模式，使已存在 `core.hooksPath` 的关联 worktree 不会让正常的 `pnpm run …` 命令失败。 +安装过程同时会运行根目录的 `postinstall` 脚本，该脚本通过 `scripts/install-lefthook.mjs` 从仓库 dev 依赖安装 lefthook。包装脚本使用 lefthook 经过评审的 `--force` 模式，确保已存在 `core.hooksPath` 的关联 worktree 不会导致正常的 `pnpm run …` 命令失败。 -如果因为依赖是从缓存恢复或 `postinstall` 被跳过而缺少钩子，手动安装： +如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装： ```sh pnpm exec lefthook install --force ``` -新克隆后先跑一次类型检查： +新克隆后请先运行一次类型检查： ```sh pnpm run typecheck ``` -这次首跑会构建 package/vendor 构建图，并跑根目录 no-emit `tsconfig.json` 图（覆盖 examples、tests 和 scripts）。根图使用同一份源码 `paths` 映射，但依赖 project references，因此 vendor 代码在它自己的 tsconfig 设置下被检查。 +首次类型检查会执行 package/vendor 的构建图，以及根目录下用于示例、测试和脚本的 no-emit `tsconfig.json` 项目图。根图使用同一份源码 `paths` 映射，但依赖 project references，因此 vendor 代码在它自己的 tsconfig 设置下被检查。 -如果准备从新克隆或新 worktree 推送，还要构建一次： +如果准备从新克隆或新 worktree 推送，还需要构建一次： ```sh pnpm run build @@ -45,29 +45,29 @@ pnpm run build ## 环境变量 -真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 读取凭证： +真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证： ```sh DEEPSEEK_API_KEY=sk-... DEEPSEEK_BASE_URL=https://... # optional ``` -`DEEPSEEK_BASE_URL` 可选，默认为公开 API。绝不要提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。 +`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。 ## Git 钩子 lefthook 在 `lefthook.yml` 中配置，作为评审前的本地早期检查点： -- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest 守卫。 +- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest 守卫； - `pre-push` 运行 `pnpm run test`、`pnpm run test:snapshot`、`pnpm run hygiene`、`pnpm run doc-sync` 和 `pnpm run verify-module-graph`。 -vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。编辑 vendor 代码前先看 `vendor/README.md`。 +vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。 -这些钩子并不与 CI 完全一致。特别是：`pre-push` 跑不带覆盖率的单元测试，而 CI 跑 `pnpm run test:coverage`；CI 还会跑 echo-agent 和 built-bin 冒烟测试，并在 Node 24 和 26 上跑矩阵。 +这些钩子并不与 CI 完全一致。特别是：`pre-push` 运行不带覆盖率的单元测试，而 CI 运行 `pnpm run test:coverage`；CI 还会运行 echo-agent 和 built-bin 冒烟测试，并在 Node 24 和 26 上运行矩阵。 ## CI 门禁 -GitHub 工作流在每个 pull request 上运行这些门禁： +GitHub 工作流在每个 Pull Request 上运行以下门禁： - `pnpm install --frozen-lockfile` - `pnpm run constraints` @@ -82,7 +82,7 @@ GitHub 工作流在每个 pull request 上运行这些门禁： - 一个 echo-agent 冒烟测试，检查演示的工具调用、工具结果和 JSONL 输出 - built-bin 冒烟测试，用纯 `node` 运行发布产物 `lib/bin.js` 入口 -`pnpm run hygiene` 是 `pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types` 的本地简写；CI 还会把 `pnpm run constraints` 作为更早的快速失败步骤单独跑一次，然后在 `pnpm run build` 之后跑完整的 hygiene 脚本。 +`pnpm run hygiene` 是 `pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types` 的本地简写；CI 还会将 `pnpm run constraints` 作为更早的快速失败步骤单独运行一次，然后在 `pnpm run build` 之后运行完整的 hygiene 脚本。 ## 日常命令 @@ -96,9 +96,13 @@ pnpm run typecheck # build package/vendor outputs, then typecheck examples, pnpm run lint # eslint . pnpm run lint:fix # eslint . --fix pnpm run doc-typecheck # compile checked TypeScript snippets in Markdown docs -pnpm run gen-cordis-catalog # regenerate docs/cordis-catalog/events-and-services.md from source -pnpm run verify-cordis-catalog # fail if the cordis events/services catalog is stale +pnpm run gen-cordis-catalog # regenerate docs/cordis-catalog/events.md + services.md from source +pnpm run verify-cordis-catalog # fail if either cordis catalog is stale +pnpm run gen-doc-graphs # regenerate generated relationship docs from source and curated graph definitions +pnpm run verify-doc-graphs # fail if generated relationship docs are stale +pnpm run gen-rfc-index # regenerate the docs/rfc/README.md index tables from the RFC tree pnpm run verify-md-wrap # fail on hard-wrapped prose paragraphs in docs/README markdown +pnpm run verify-mermaid # fail if a ```mermaid diagram has invalid Mermaid syntax pnpm run verify-type-equiv # fail if a ```ts type-equiv doc block drifts from its source type pnpm run verify-doc-budgets # fail if a budgeted standing doc exceeds its word ceiling pnpm run doc-sync # all Markdown/doc gates; see the doc-sync script in package.json for the full list @@ -109,7 +113,7 @@ pnpm run verify-node-next-types # fail if built declarations are not NodeNext-c pnpm run hygiene # knip, publint, workspace constraints, and NodeNext declaration check ``` -改动 package 的公开行为时，在同一个变更里更新相关 README 或 JSDoc。`pnpm run doc-sync` 能抓住被检查的 TypeScript 片段、cordis 事件/服务目录漂移和硬折行的 markdown 段落，但更广泛的行文/API 同步仍需评审把关。 +修改 package 的公开行为时，请在同一个变更中更新相关 README 或 JSDoc。`pnpm run doc-sync` 能检测到被检查的 TypeScript 片段、生成文档的新鲜度、Markdown 换行/链接漂移、type-equiv、翻译配对、Mermaid 语法和文档预算，但更广泛的行文/API 同步仍需评审把关。 ## 演示 @@ -133,24 +137,24 @@ pnpm run demo:acp ## TODO 标记 -用三种注释标签之一标记代码中的已知问题，按紧急程度排序： +请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序： -- `FIXME`——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 `FIXME` 出门。 -- `TODO`——应当尽快修复的问题，等资源到位就处理。 -- `XXX`——也许某天会修的问题；优先级最低，不作承诺。 +- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`； +- `TODO`：应当尽快修复的问题，等资源到位即可处理； +- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。 -选择与紧急程度匹配的标签，让扫代码的人一眼分清「发布阻塞」和「有空再说」。 +请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。 ## 逐字记录类型（`ts type-equiv`） -[核心数据结构](core-data-structures/core.md)文档粘贴真实的类型定义，让读者看到确切的形状。为防止粘贴内容在源码变化时漂移，把它围栏成 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号： +[核心数据结构](core-data-structures/core.md)文档粘贴真实的类型定义，让读者看到确切的形状。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号： ```json { "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。 ## 架构上下文 -改动 `packages/` 下的任何东西之前先读 `docs/architecture.md`。这套代码围绕 Cordis 插件、事件溯源的会话、类型化的服务 seam（扩展点）与显式扩展点构建。 +在修改 `packages/` 目录下的任何内容之前，请先阅读 `docs/architecture.md`。这套代码围绕 Cordis 插件、事件溯源的会话、类型化的服务 seam 与显式扩展点构建。 diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md index b72d810afc..6376b3964f 100644 --- a/docs/i18n/style-samples.md +++ b/docs/i18n/style-samples.md @@ -54,7 +54,7 @@ > Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. The recorded hash also recovers the exact last-confirmed text of either side (`git cat-file -p `), so an out-of-sync pair is updated by diffing the edited side against its last-confirmed state and patching the counterpart minimally — never by re-translating whole files. -系统采用文件 blob 哈希而非提交哈希记录状态。同一 PR 内修改文件时，可通过 `git hash-object foo.md` 直接算出对应哈希，仅对比文件内容即可判断双语文档是否同步。通过记录的哈希值，可使用 `git cat-file -p ` 还原上次确认对齐时两侧的原文。当双语文档不一致时，只需对比修改版本与上次确认版本的差异，最小幅度同步修改另一侧译文，无需全文重新翻译。 +系统采用文件 blob hash 而非 commit hash 记录状态。同一 PR 内修改文件时，可通过 `git hash-object foo.md` 直接算出对应 blob hash，仅对比文件内容即可判断双语文档是否同步。通过记录的 blob hash，可使用 `git cat-file -p ` 还原上次确认对齐时两侧的原文。当双语文档不一致时，只需对比修改版本与上次确认版本的差异，最小幅度同步修改另一侧译文，无需全文重新翻译。 ## ⑤ 政策声明 diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md index 408048a66f..ae6f24acdb 100644 --- a/docs/i18n/terminology.md +++ b/docs/i18n/terminology.md @@ -1,148 +1,165 @@ # Terminology -本表约定本仓库的中英术语统一译法。各列语义： +本表约定本仓库的中英术语统一译法。 -- **中文** — 正文中的固定译法；写「保留英文」表示不译。 -- **首次出现** — 术语在一篇文档中第一次出现时的完整写法（含括注）；之后只写「中文」列的形式。组合词已括注过的成分，单独出现时不再括注。 -- **不要译作** — 禁用译法，逐项列出；出现任何一项即评审阻断。 -- **备注** — 语境区分、裁定出处等自由说明；不承载可执行规则。 +**通用规则：** +- "中文"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。 +- 首次出现按"首次出现"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。 +- "不要译作"列为严格禁止的译法。 +- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。 + +## 缩写类（中英文文本中均使用缩写） | English | 中文 | 首次出现 | 不要译作 | 备注 | |---|---|---|---|---| -| ACP | ACP | ACP（Agent Client Protocol） | | | -| AI | AI | 人工智能（AI） | | | -| API | API | | | real-API 作定语时可译「真实接口」（如 real-API tests → 真实接口测试） | -| CI | CI | | | | -| CLI | CLI | 命令行界面（CLI） | | | -| Cordis | Cordis | | | 保留英文 | -| Function Calling | Function Calling | Function Calling（函数调用） | | | -| HMR | HMR | 热模块替换（HMR） | | | -| JSON Schema | JSON Schema | | | | -| JSONL | JSONL | | | | -| lint | lint | | | | -| loader | loader | | | | -| LLM | LLM | 大语言模型（LLM） | | | -| MCP | MCP | | | | -| PR | PR | PR（pull request） | | | -| RAG | RAG | 检索增强生成（RAG） | | | -| SDK | SDK | | | | -| SSE | SSE | SSE（Server-Sent Events） | | | -| agent | agent | agent（智能体） | | 括注只落在 agent 单独首现处；组合词见下行 | -| agent harness, agent workflow, agent loop, agent skill | 保留英文 | | | agent 组合词整体保留英文、不括注；其中的 workflow/loop/skill 不单独拆译；未列出的 agent 组合词同此处理 | -| backlog | backlog | | | 双语翻译语境指待翻清单 | -| blob hash | blob 哈希 | | | git 对象哈希；`git hash-object` 的结果 | -| commit hash | 提交哈希 | | | | -| hash | 哈希 | | | 代码与命令中保留英文（如 `git hash-object`、`` 占位符） | -| doc-sync | doc-sync | | | 仓库门禁名，保留英文 | -| e2e | e2e | | | | -| fiber | fiber | fiber（插件运行时） | | | -| fixture | fixture | | | 指测试前置数据或环境 | -| fork | fork | | | 保留英文 | -| harness | harness | | | 保留英文 | -| manifest | manifest | | | 描述模块或工具元数据的文件 | -| monorepo | monorepo | | | | -| package | package | | | 保留英文；指 npm 包（`@deepseek-ai/dsh-*`） | -| schema DSL | schema DSL | | | | -| schema | schema | | | 保留英文 | -| seam | seam | seam（扩展点） | | 同句已出现「扩展点」（extension point）时不加括注，直接写 seam，避免一词两指 | -| skill | skill | skill（技能） | | | -| spawn | spawn | | | 保留英文 | -| steering | steering | steering（中途引导） | | | -| subagent | subagent | subagent（子 agent） | | | -| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志（event log） | -| waterfall | waterfall | waterfall（瀑布式事件） | | | -| worktree | worktree | | | git 工作区概念，保留英文 | -| wire format | 协议格式 | 协议格式（wire format） | | | -| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | | -| adapter | 适配器 | | | | -| append-only | 仅追加 | | | | -| artifact | 产物 | | | | -| block | 块 | | | | -| background task | 后台任务 | | | | -| backend | 后端 | | | | -| capability | 能力 | | | | -| cancel | 取消 | | | | -| checkpoint | 检查点 | | | | -| chunk | 分片 | | | | -| compaction | compaction | compaction（上下文压缩） | | 正文优先保留英文 | -| consumer | 消费方 | | | | -| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指“另一侧”时可写「另一侧」 | -| content block | 内容块 | | | | -| config | 配置 | | | | -| context | 上下文 | | | | -| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | | -| contract | 契约 | | | 如：配对契约（pairing contract）；另见 adapter contract | -| coverage | 覆盖率 | | | | -| crash recovery | 崩溃恢复 | | | | -| dispose | dispose | dispose（释放资源） | | 正文优先保留英文 | -| durability | 持久性 | | | | -| enforcement frontier | 强制边界 | | | i18n 机制词：manifest `required` 清单所划的门禁生效范围 | -| event log | 事件日志 | | | | -| event | 事件 | | | | -| event stream | 事件流 | | | | -| event-sourced | 事件溯源 | | | DDD 社区通行译法 | -| executor | 执行器 | | | | -| extension | 扩展 | | | | -| fail-fast | 快速失败 | | | | -| fenced code block | 围栏代码块 | | | MDN 中文同译 | -| finish reason | 结束原因 | | | | -| fingerprint | 指纹 | | | i18n 机制词：`.zh.md` 首行记录英文源 blob hash 的 `i18n-source` 注释 | -| foreground run | 前台运行 | | | | -| freshness | 新鲜度 | | | MDN HTTP 缓存中文同译（freshness lifetime → 新鲜度生命周期）；指译文相对英文源的同步状态 | -| hook | 钩子 | | | | -| implementation | 实现 | | | | -| inference | 推理（inference） | | | 每次提及时保留英文括注，避免与 reasoning 混淆 | -| info string | 信息字符串 | | | CommonMark 中文同译；代码围栏 ``` 之后的语言标注 | -| injection | 注入 | | | | -| interface | 接口 | | | | -| integration | 集成 | | | | -| language switcher | 语言切换行 | | | i18n 机制词：双语配对文件顶部的互链行 | -| memory | memory / 记忆 / 内存 | | | 按上下文区分：agent memory 译为“记忆”；resource/memory usage 译为“内存” | -| message | 消息 | | | | -| mock | mock | | | 保留英文；指测试替身 | -| mod | 模组 | | | 区别于 module（模块）；plugin 译作「插件」 | -| model provider | 模型提供方 | | | | -| module | 模块 | | | | -| orphan | 孤立 | | 孤儿 | git 官方中文同译（如「孤立分支」）；指英文源已不存在的 `.zh.md`；进程语境按 OS 惯用语译「孤儿进程」 | -| pairing | 配对 | | | | -| permission | 权限 | | | | -| persistence | 持久化 | | | | -| pipeline | 流水线 | | | | -| plugin | 插件 | | | mod 对应“模组” | -| prompt | 提示词 | | | | -| provider | 提供方 | | | | -| provider-neutral | 提供方无关 | | | | -| quality gate | 质量门禁 | | | | -| registry | 注册表 | | | | -| reasoning | 推理（reasoning） | | | 需要和 inference 区分时保留英文括注；`reasoning_content` 译为“思考内容” | -| replay | 回放 | | | | -| resume | 恢复 | | | | -| runtime | 运行时 | | | | -| sandbox | 沙箱 | | | | -| service | 服务 | | | | -| session | 会话 | | | | -| session event | 会话事件 | | | | -| sidecar record | 伴随记录 | | 旁挂记录 | 指 `.i18n.yaml` 这类随主文件存放的记录文件 | -| smoke test | 冒烟测试 | | | | -| snapshot | 快照 | | | | -| source of truth | 真源 | 真源（source of truth） | | 评审裁定译法；如后续裁定调整，改此表即可 | -| spine | 主干 | | | | -| staged | 暂存 | | | git 官方中文同译 | -| stale | 陈旧 | | | MDN HTTP 缓存中文同译，与「新鲜（fresh）」成对；门禁输出保留英文 `stale`；expired 才译「过期」 | -| step | 步骤 | | | | -| stream | 流 | | | | -| streaming | 流式输出 | | | | -| structural signature | 结构签名 | | | i18n 机制词：配对门禁比对的有序结构序列 | -| system prompt | 系统提示词 | | | | -| taxonomy | 分类体系 | | | | -| token usage | token 用量 | | | | -| thinking | thinking | | | API 字段保留；模型模式译为“思考” | -| tool | 工具 | | | | -| tool call | 工具调用 | | | | -| tool result | 工具结果 | | | | -| tool schema | 工具 schema | | | | -| toolkit | 工具包 | | | | -| turn | 轮次 | | | | -| typecheck | 类型检查 | | | | -| vocabulary | 词汇 | | | | -| workflow | 工作流 | | | | +| ACP | ACP | ACP（Agent Client Protocol） | | | +| AI | AI | AI（人工智能） | | | +| API | API | | | | +| CI | CI | | | | +| CLI | CLI | CLI（命令行界面） | | | +| e2e | e2e | | | | +| HMR | HMR | HMR（热模块替换） | | | +| JSON Schema | JSON Schema | | | | +| JSONL | JSONL | | | | +| LLM | LLM | LLM（大语言模型） | | | +| MCP | MCP | | | | +| PR | PR | PR（Pull Request） | | | +| RAG | RAG | RAG（检索增强生成） | | | +| SDK | SDK | | | | +| SSE | SSE | SSE（Server-Sent Events） | | | + +## 英文类（中英文文本中均使用英文） + +| English | 中文 | 首次出现 | 不要译作 | 备注 | +|---|---|---|---|---| +| agent | agent | agent（智能体） | | | +| agent harness | agent harness | | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按 agent 行处理 | +| agent loop | agent loop | agent loop（智能体循环） | | | +| backlog | backlog | backlog（待翻清单） | | 仅在双语翻译语境里括注`待翻清单` | +| blob hash | blob hash | | | `git hash-object` 的结果 | +| Cordis | Cordis | | | | +| dispose | dispose | dispose（资源释放） | | | +| doc-sync | doc-sync | doc-sync（文档同步门禁） | | | +| fiber | fiber | fiber（插件运行时） | | | +| fixture | fixture | fixture（测试前置数据） | | | +| fork | fork | | | | +| Function Calling | Function Calling | Function Calling（函数调用） | | | +| harness | harness | | | | +| harness engineering | harness engineering | | | | +| lint | lint | | | | +| mock | mock | | | 保留英文；指测试替身 | +| loader | loader | | | | +| manifest | manifest | manifest（元数据清单） | | | +| monorepo | monorepo | | | | +| package | package | | | 保留英文；指 npm 包（`@deepseek-ai/dsh-*`） | +| schema | schema | | | | +| schema DSL | schema DSL | | | | +| seam | seam | | | 与 `extension point` 是不同概念；根据具体语境，可译为`服务边界`或`可替换点` | +| skill | skill | skill（技能） | | | +| spawn | spawn | | | | +| steering | steering | steering（中途引导） | | | +| subagent | subagent | | | | +| thinking | thinking | | | API 字段保留英文；描述模型模式时译为`思考` | +| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 | +| waterfall | waterfall | waterfall（瀑布式事件） | | | +| worktree | worktree | | | git 工作区概念 | + +## 双语类（中英文文本各自使用中英文） + +| English | 中文 | 首次出现 | 不要译作 | 备注 | +|---|---|---|---|---| +| adapter | 适配器 | | | | +| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | | +| append-only | 仅追加 | | | | +| artifact | 产物 | | | | +| backend | 后端 | | | | +| background task | 后台任务 | | | | +| block | 块 | | | | +| cancel | 取消 | | | | +| capability | 能力 | | | | +| checkpoint | 检查点 | | | | +| chunk | 分片 | | | | +| compaction | 压缩 | 压缩（compaction） | | | +| config | 配置 | | | | +| consumer | 消费方 | | | | +| content block | 内容块 | | | | +| context | 上下文 | | | | +| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 | +| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | | +| contract | 契约 | | | 如：`pairing contract` →`配对契约` | +| coverage | 覆盖率 | | | | +| crash recovery | 崩溃恢复 | | | | +| durability | 持久性 | | | | +| enforcement frontier | 强制边界 | | | i18n 配对机制用语：manifest `required` 清单所划的门禁生效范围 | +| event | 事件 | | | | +| event log | 事件日志 | | | | +| event stream | 事件流 | | | | +| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 | +| executor | 执行器 | | | | +| extension | 扩展 | | | | +| extension point | 扩展点 | | | 注意与 `seam` 区分 | +| fail-fast | 快速失败 | | | | +| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 | +| fingerprint | 指纹 | | | i18n 配对机制用语：`.zh.md` 首行记录英文源 blob hash 的注释 | +| finish reason | 结束原因 | | | | +| foreground run | 前台运行 | | | | +| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 | +| hook | 钩子 | | | | +| implementation | 实现 | | | | +| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 | +| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 | +| injection | 注入 | | | | +| integration | 集成 | | | | +| interface | 接口 | | | | +| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 | +| memory | 记忆 / 内存 | | | 与 `agent` 搭配时译为`记忆`（如 `agent memory` →`智能体记忆`）；指系统资源时译为`内存` | +| merge | 合并 | | | | +| message | 消息 | | | | +| mod | 模组 | | | | +| model provider | 模型提供方 | | | | +| module | 模块 | | | | +| orphan | 孤立 | | 孤儿 | 指英文源已不存在的 `.zh.md` | +| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 | +| pairing | 配对 | | | | +| permission | 权限 | | | | +| persistence | 持久化 | | | | +| pipeline | 流水线 | | | | +| plugin | 插件 | | | | +| prompt | 提示词 | | | | +| provider | 提供方 | | | | +| provider-neutral | 提供方无关 | | | | +| quality gate | 质量门禁 | | | | +| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 | +| reasoning_content | 思考内容 | | | | +| registry | 注册表 | | | | +| replay | 回放 | | | | +| resume | 恢复 | | | | +| runtime | 运行时 | | | | +| sandbox | 沙箱 | | | | +| service | 服务 | | | | +| session | 会话 | | | | +| session event | 会话事件 | | | | +| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 | +| smoke test | 冒烟测试 | | | | +| snapshot | 快照 | | | | +| source of truth | 真源 | | | | +| spine | 主干 | | | | +| staged | 暂存 | | | 沿用 git 官方中文翻译 | +| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` | +| step | 步骤 | | | | +| stream | 流 | | | | +| streaming | 流式输出 | | | | +| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） | +| system prompt | 系统提示词 | | | | +| taxonomy | 分类体系 | | | | +| token usage | token 用量 | | | | +| tool | 工具 | | | | +| tool call | 工具调用 | | | | +| tool result | 工具结果 | | | | +| tool schema | 工具 schema | | | | +| toolkit | 工具包 | | | | +| turn | 轮次 | | | | +| typecheck | 类型检查 | | | | +| vocabulary | 词汇 | | | | +| wire format | 协议格式 | 协议格式（wire format） | | | +| workflow | 工作流 | | | | diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md index 573f125878..db707730fa 100644 --- a/docs/i18n/translation-prompt.md +++ b/docs/i18n/translation-prompt.md @@ -14,6 +14,18 @@ 历史模板的 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 占位符与 `%%` 分段协议已废弃：本模板按整文档翻译（非分段），输出协议为下方三段 XML。 +## Few-shot 金标 + +流水线的 few-shot 是**整文档级**的中英对照，不是模板内嵌的句子级正误例（那是最小抽样）。few-shot 集取自以下 5 组人工定稿的配对文档，以仓库当前版本为准、随仓库更新： + +- `README.md` ↔ `README.zh.md` +- `docs/development.md` ↔ `docs/development.zh.md` +- `docs/i18n/README.md` ↔ `docs/i18n/README.zh.md` +- `docs/i18n/translation-rules.md` ↔ `docs/i18n/translation-rules.zh.md` +- `docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md` ↔ 对应 `.zh.md` + +注入方式：在系统消息（本模板）之后、待译文档之前，每组作为一轮示例对话——user 消息为源文档全文，assistant 消息为定稿译文全文（不带三段 XML 包装；只有真实请求要求三段输出）。上下文紧张时按上列顺序从后往前裁剪组数。这 5 组也是评审校准锚点（见 [style-samples.md](style-samples.md)），改动任何一组即改变流水线行为。 + ## 模板正文 ````text diff --git a/docs/i18n/translation-rules.i18n.yaml b/docs/i18n/translation-rules.i18n.yaml index f1aa737d08..d340ff42b8 100644 --- a/docs/i18n/translation-rules.i18n.yaml +++ b/docs/i18n/translation-rules.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write translation-rules.md: 3e99aa5432ccd904f702238e9b802a9ed9bf6832 -translation-rules.zh.md: 78778907f959d62dad2c9b4c02baf1f664791a43 +translation-rules.zh.md: 0ff2ab43d59c6e0dd07e20e2f1a0a1c28c2f245c diff --git a/docs/i18n/translation-rules.zh.md b/docs/i18n/translation-rules.zh.md index 78778907f9..0ff2ab43d5 100644 --- a/docs/i18n/translation-rules.zh.md +++ b/docs/i18n/translation-rules.zh.md @@ -2,13 +2,13 @@ [English](translation-rules.md) | 中文 -本文规定如何在本仓库文档配对的两侧之间进行翻译。两种语言同权（见 [README.md](README.md)）：一次变更用任一语言撰写，那一侧就是这次更新的源——本文的规则约束的是产出或更新另一侧。这些规则对人和 agent（智能体）同等生效；应用它们的进仓 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）**／**禁止（MUST NOT）**会卡门禁或评审；**应当（SHOULD）**偏离时要说明理由；**可以（MAY）**自行裁量。 +本文规定：如何在本仓库文档配对的中英文两种语言之间进行翻译。两种语言同权（见 [README.md](README.md)）：每次变更可以用任一语言撰写，被编辑的一侧即为本次更新的源；本文的规则约束如何产出或更新对侧文件。这些规则对人类和 agent（智能体）同等生效；应用这些规则的仓库内置 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）** ／ **禁止（MUST NOT）** 会卡门禁或评审；**应当（SHOULD）** 偏离时要说明理由；**可以（MAY）** 自行裁量。 ## 忠实性 -- 另一侧必须说撰写侧所说的话——不添加行为、前置条件、警告、版本声明或示例，也不丢弃任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜：改正错的那一侧，并在同一个变更里把另一侧带上。 -- 另一侧应当读起来是其语言自然的技术文字，而不是逐词对照。翻译语义，在目标语言语法需要处重组句子，并保持原作者的语域——简练的保持简练。 -- 不要翻译不可译的东西：一句话如果依赖源语言的习语而无法自然转换，就翻译它的意思，而不是习语本身。 +- 对侧文件*必须*传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。 +- 对侧文件读起来*应当*是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。 +- 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。 ## 行文 @@ -23,47 +23,47 @@ 形状由配对门禁强制，译者不需要用流畅度去换结构——在框架内自然行文即可。配对的两个文件必须在以下方面一一对应： -- 标题层级（相同级别、相同顺序——标题的**文字**要翻译）， -- 列表形态与编号， -- 表格（相同的列、相同的行序；表头单元格按术语表翻译）， -- 围栏代码块——**逐字节一致，包括注释**；代码属于受验证的范围（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移， -- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）——原样保留，从不翻译或重排， -- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标——按约定是 `.md` 路径而非 `.zh.md` 兄弟文件——这样某对文档先于相邻文件落地时，链接也永不悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。 +- 标题层级（相同级别、相同顺序；标题的**文字**要翻译）； +- 列表形态与编号； +- 表格（相同的列、相同的行序；表头单元格按术语表翻译）； +- 围栏代码块：**逐字节一致，包括注释**。代码属于受验证的范围（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移； +- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排； +- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 `.md` 路径而非 `.zh.md` 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。 本仓库的 Markdown 约定对 `.zh.md` 文件原样生效：一个段落一个物理行（`verify-md-wrap`）、相对链接必须可解析（`verify-md-links`）、文件末尾恰好一个换行。 ## 术语 -- [terminology.md](terminology.md) 是双向的术语真源。翻译前先加载它；翻译中，表内的每个术语都必须严格按表规定的译法呈现，包括首次出现的括注（如首现写 `agent（智能体）`，之后写 `agent`）与「不要译作」的禁项。中文先行撰写时，英文另一侧同样按表中英文列使用术语。 -- 表中**没有**的技术术语，只有当某个主要中文 OSS 或厂商文档已有成型译法时（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档）才可以翻译。在 PR 中注明先例出处。 -- **没有**成型先例的术语，译文中必须保留英文，并且必须在 PR 描述的「待定术语」下列出、附上建议译法交评审者定夺。禁止就地发明中文译法——无先例的翻译恰恰制造了术语表要防止的歧义。定下来的术语随后在同一个 PR 或后续 PR 进入 [terminology.md](terminology.md)。 +- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；翻译过程中，表内的每个术语都*必须*严格按表中规定的译法呈现，包括首次出现的括注（如首现写 `agent（智能体）`，之后写 `agent`）与「不要译作」的禁项。中文先行撰写时，英文对侧同样按表中英文列使用术语。 +- 表中**没有**的技术术语，只有当某个主要中文 OSS 或厂商文档已有成型译法时（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档）才*可以*翻译。请在 PR 中注明先例出处。 +- **没有**成型先例的术语，译文中*必须*保留英文，并且*必须*在 PR 描述的「待定术语」下列出，附上建议译法交评审者定夺。*禁止*就地发明中文译法，因为无先例的翻译恰恰会制造术语表要防止的歧义。确定下来的术语随后在同一个 PR 或后续 PR 中进入 [terminology.md](terminology.md)。 ## 排版 -本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 `AGENTS.md`）。下面的中西文混排规则遵循 [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 中文翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)与[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)的跨项目共识，其根据是 [W3C clreq](https://www.w3.org/TR/clreq/) 与 GB/T 15834—2011： +本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 `AGENTS.md`）。以下中西文混排规则遵循 [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 中文翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) 与[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)的跨项目共识，其根据是 [W3C clreq](https://www.w3.org/TR/clreq/) 与 GB/T 15834—2011： -- 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。 -- 中文行文必须使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。 -- 并列顿开：中文的并列项之间用顿号（、），不用逗号。 -- 禁止使用全角数字或全角拉丁字母——永远不写 `１２３`，永远写 `123`。 -- 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek——除非引用代码，否则绝不写 `github`／`Github`。 +- *必须*在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。 +- 中文行文*必须*使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。 +- 顿号：中文的并列项之间使用顿号（、），而非逗号。 +- *禁止*使用全角数字或全角拉丁字母：永远不写 `１２３`，永远写 `123`。 +- 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek。除非引用代码，否则绝不写 `github`／`Github`。 - 第二人称用「你」，不用「您」（与 Vue、Kubernetes 中文约定及本仓库的直接语气一致）。 -- 强调标记（`**加粗**`、`*斜体*`）落在与另一侧相同的文字段上；中文没有斜体，渲染效果可能看不出差别——不要用引号或其他装饰替代。 +- 强调标记（`**加粗**`、`*斜体*`）落在与对侧相同的文字段上。中文没有斜体，渲染效果可能看不出差别，不要用引号或其他装饰替代。 -## 质量线 +## 质量标准 -- 一对文档的完成标准：一位双语工程师只读其中任一文件，得到与另一文件读者完全相同的信息——相同的事实、相同的告诫、相同的语气——并且没有任何多余的内容。 -- 交付前，对照本文自查一遍，并**只读另一侧**再通读一遍、不看源侧对照；没有源文锚着，别扭的表述更容易被听出来。 -- 机械契约（一致性记录、切换行、结构、折行、链接）由 `pnpm run verify-translation-pairing` 和 `doc-sync` 的其余门禁检查——跑门禁；门禁覆盖的不要手工核对。 +- 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。 +- 交付前，请对照本文自查一遍，并**单独通读对侧文件**，不与源侧对照；不对照原文时，更容易察觉别扭的表达。 +- 机械契约（一致性记录、切换行、结构、折行、链接）由 `pnpm run verify-translation-pairing` 和 `doc-sync` 的其余门禁检查。请运行门禁；门禁已覆盖的内容无需手工核对。 ## 参考资料 本文各规则引用的权威出处，供想了解底层依据的人和 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《翻译服务译文质量要求》：国家标准；本文「忠实性」与「术语」两节将其三项基本要求（忠实原文、术语统一、行文通顺）落实为可操作的规则。 diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml index 1ef023ec50..f409941924 100644 --- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml +++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write 2026-07-02-bilingual-docs-and-pairing-gate.md: 764ad5a9345c2a138b56e9cedb54848a5f7d6054 -2026-07-02-bilingual-docs-and-pairing-gate.zh.md: f039fbe3fa44cb379905bbea9a4692af19d71230 +2026-07-02-bilingual-docs-and-pairing-gate.zh.md: c752d76f12f556ce190bf80c4f3a531c0821be8e diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md index f039fbe3fa..c752d76f12 100644 --- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md +++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md @@ -1,36 +1,38 @@ -# 通过配对兄弟文件与配对门禁实现双语文档 +# RFC：通过配对兄弟文件与配对门禁实现双语文档 + +Status: implemented [English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文 -## 背景 +## 问题 -本仓库的 README 与 docs 目录树会被公司内外的人和 agent（智能体）以中英两种语言阅读。没有机制、纯靠手工维护第二语言，正是译文腐烂的方式：一侧继续演进，另一侧默默地说谎，而没有门禁会注意到。对这类不变式，本仓库一贯的答案是把它编码成机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。 +本仓库的 README 与 docs 目录树会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。 ## 决策 -- **配对兄弟文件，两种语言同权。**一对文档是三个兄弟文件：英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典——一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束这对文件的是两侧必须说同样的话，且配对整体合入（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。 -- **旁挂记录两侧 blob hash，使一致性可检查。**`foo.i18n.yaml` 保存两侧文件在上一次确认一致状态下各自的完整 git blob hash。此后改了任一侧而没重新确认配对，都能被机械检测出来——纯内容比较、无需查询历史——而且同一个 PR 里改动的文件也能算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）产生一份可评审的 yaml diff：确认一致在 PR 里是一个显式、可见的动作。 -- **`verify-translation-pairing` 加入 `doc-sync`。**门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行：required 的配对存在；任何已存在的配对完整（三个文件齐全）且一致（两个 hash 都匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单是一个棘轮：每个合入的翻译批次把自己的文件加进去，覆盖面只增不减。 -- **翻译是 agent 的工作，由人评审。**进仓的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 同一模式：skill 承载工作流，并把真源让给文档。 +- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。 +- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR 内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。 +- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。 +- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 模式相同：skill 承载工作流，并将文档作为真源。 ## 曾考虑的替代方案 -- **英文为正典源、指纹放在译文内**——本 RFC 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 RFC，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的旁挂记录取代了文件内的单向指纹；blob hash 的机制原样保留。 -- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**——否决：本仓库没有把 locale 映射到路由的文档站框架，挪动每个英文文件会搅动所有既有交叉引用，且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑而不是原样工作。 -- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**——否决：适合有独立发布节奏的文档产品，对 monorepo 自己的文档而言过重；还会把译文置于本仓库门禁够不到的地方。 -- **中英混排单文件（一个文件、两种语言）**——否决：每个 diff 都翻倍，破坏一段一行约定的 diff 工效，且局部不一致不可见。 -- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**——否决，改用 blob hash：同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。 -- **比较配对两侧的 git 时间戳（无记录）**——否决：纯格式化的改动会误报，一次无关改动之后提交的另一侧会漏报；只有内容同一性这个信号与门禁的承诺名实相符。 +- **英文为正典源、指纹放在译文内**：本 RFC 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 RFC，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。 +- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。 +- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。 +- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。 +- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。 +- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。 ## 业界先例 -带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`）——但这些仓库都没有在 CI 里**强制**配对或一致性；约定纯靠评审维系。一致性自动化存在于中国之外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit、为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计把两者结合：中文生态的文件布局，加 hash 对门禁，再加一个进仓 agent skill（技能）替代 bot 服务。 +带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。 ## 后果 -- 修改已配对文档的任一侧，同一个 PR 就有义务更新另一侧并重新记录配对——门禁把 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。 -- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对一致」可以从 yaml 的 git blame 直接回答。 -- 两侧说法冲突时，没有机械规则裁决谁赢——由 PR 评审裁决。这是同权的代价，是有意接受的：另一个选项（正典语言）禁止中文先行撰写。 -- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让它们的生成器在输出英文的同时输出中文，届时移出排除清单。 -- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（`--list`），不是红的 CI，因此配对按可评审的批次落地，无需一个巨型 PR。新文档是例外——文件名日期在 manifest `requiredSince` 当天或之后的文档，要么连同配对一起合入，要么不合入，因此 backlog 只会缩小。 -- 记录的 hash 兼作更新工具（`git cat-file -p ` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），所以这套机制从不强迫整篇重译。 +- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。 +- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。 +- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。 +- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。 +- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。 +- 记录的 hash 兼作更新工具（`git cat-file -p ` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），因此这套机制从不强迫整篇重译。