diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml index 1702dcf2a9..1959a44b4d 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: ea5f2e5d08acbaf1dfce4661530218dbf1a051b9 -development.zh.md: d7263d63ce2d3b851d38e633641c0324c9fb0460 +development.zh.md: 9c0cc23373b0f4feba8538fcbd25b38a483e0ba0 diff --git a/docs/development.zh.md b/docs/development.zh.md index d7263d63ce..9c0cc23373 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -2,14 +2,14 @@ [English](development.md) | 中文 -本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，并帮助你了解本地钩子、日常检查与 CI 门禁。 +本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建、日常工作流与 CI 流程；设计动机与技术权衡请查阅相应 RFC。 ## 前置条件 - Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 RFC](rfc/implemented/process/2026-07-06-node-engine-floor.md)。 - 启用了 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 测试。 ## 首次搭建 @@ -59,7 +59,7 @@ DEEPSEEK_BASE_URL=https://... # optional lefthook 在 `lefthook.yml` 中配置，作为评审前的本地早期检查点： - `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`。 +- `pre-push` 运行 `pnpm run check:pre-push`，其调度器并发运行单元测试、快照测试、构建、module-graph 新鲜度，以及 `pnpm run hygiene` 与 `pnpm run doc-sync` 的各成员门禁。 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。 diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml index 6764f01a21..d9312030c9 100644 --- a/docs/i18n/README.i18n.yaml +++ b/docs/i18n/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -README.md: 30b9e53383ef591898505375662ec94d732de304 +README.md: d600773af2be156f52746c5bbd1853ff2ab46c14 README.zh.md: eac836e7c310945ec345db9974be9f1deaae4c60 diff --git a/docs/i18n/README.md b/docs/i18n/README.md index 30b9e53383..d600773af2 100644 --- a/docs/i18n/README.md +++ b/docs/i18n/README.md @@ -26,6 +26,7 @@ This repo's documentation is read by people and agents both inside and outside t 1. Every file listed as `required` in [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) has a complete pair. 2. Every pair that exists at all — required or not — is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table column counts, list kinds, and every link target apart from the switcher. 3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. +4. Every date-named document (`yyyy-mm-dd-*.md`) dated on or after the manifest's `requiredSince` cutoff has a complete pair — new documents merge bilingual from birth. `pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok — and is the work list for translation batches. It never fails; it reports. diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md index f5dcb1f779..69f0e170e0 100644 --- a/docs/i18n/terminology.md +++ b/docs/i18n/terminology.md @@ -63,6 +63,7 @@ | thinking | thinking | | | API 字段保留英文；描述模型模式时译为`思考` | | transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 | | waterfall | waterfall | waterfall（瀑布式事件） | | | +| wheel | wheel 包 | | | Python 打包格式 | | worktree | worktree | | | git 工作区概念 | ## 双语类（中英文文本各自使用中英文） @@ -92,6 +93,7 @@ | contract | 契约 | | | 如：`pairing contract` →`配对契约` | | coverage | 覆盖率 | | | | | crash recovery | 崩溃恢复 | | | | +| deploy root | 部署根目录 | | | | | durability | 持久性 | | | | | enforcement frontier | 执行红线 | | 强制边界 | i18n 配对机制用语：manifest `required` 清单所划的门禁生效范围；与金标样例（style-samples ⑦）一致 | | event | 事件 | | | | @@ -124,6 +126,7 @@ | orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 | | orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 | | pairing | 配对 | | | | +| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | | | permission | 权限 | | | | | persistence | 持久化 | | | | | pipeline | 流水线 | | | | @@ -140,6 +143,7 @@ | runtime | 运行时 | | | | | sandbox | 沙箱 | | | | | service | 服务 | | | | +| serving surface | 对外服务接口 | | | | | session | 会话 | | | | | session event | 会话事件 | | | | | sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 | @@ -162,6 +166,7 @@ | tool schema | 工具 schema | | | | | toolkit | 工具包 | | | | | turn | 轮次 | | | | +| VFS | VFS | 虚拟文件系统（VFS） | | | | typecheck | 类型检查 | | | | | vocabulary | 词汇 | | | | | wire format | 协议格式 | 协议格式（wire format） | | | diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md index 211d36a175..9978e2d29b 100644 --- a/docs/i18n/translation-prompt.md +++ b/docs/i18n/translation-prompt.md @@ -11,6 +11,8 @@ | `{{source_lang}}` | 源语言名（`English` / `Chinese`） | 由改动侧文件推断：`.zh.md` 被改则为 `Chinese` | | `{{target_lang}}` | 目标语言名（`Chinese` / `English`） | 与 `{{source_lang}}` 相对 | | `{{terminology}}` | [terminology.md](terminology.md) 的完整表格（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 | +| `{{source_filename}}` | 源文档的 basename（如 `foo.md`） | 由流水线从待译文件路径取得 | +| `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 由 `{{source_filename}}` 派生 | 历史模板的 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 占位符与 `%%` 分段协议已废弃：本模板按整文档翻译（非分段），输出协议为下方三段 XML。 @@ -40,8 +42,8 @@ You are a senior technical translator specializing in LLM and agent development - Fenced code blocks must be byte-identical to the source, including ALL comments inside them. Do NOT translate comments inside code blocks. This is a hard rule with no exceptions. - Inline code spans (commands, flags, paths, API names, version numbers) must be kept verbatim. Never translate or reformat them. - Every relative link must point to the same target as in the source. Link text is translated; link targets are not. -- Language switcher line: when translating into Chinese, write `[English](source-filename.md) | 中文`. When translating into English, write `English | [中文](source-filename.zh.md)`. Do NOT copy the switcher line from the source file unchanged — you must flip the link direction. -- After a closing bold marker `**`, always insert a space before the next character. +- Language switcher line: the source document's filename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1 heading. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1. Emit this line even when the source file has no switcher yet (a brand-new pair); when the source does have one, flip the link direction — never copy it unchanged. +- After a closing bold marker `**`, insert a space before the next character when that character is a Latin letter or digit. Never insert a space before full-width (Chinese) punctuation. ### Tone and Style - The translation must read as if originally written in the target language by a native speaker. If an expression sounds like a word-for-word rendering from the source language, rephrase it. diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts index c0c56ffe46..8297d13fe8 100644 --- a/scripts/verify-translation-pairing.ts +++ b/scripts/verify-translation-pairing.ts @@ -257,7 +257,7 @@ for (const req of manifest.required) { // 2. Date-named documents (RFCs) dated on/after the requiredSince cutoff merge // bilingual: a new RFC lands with its pair or not at all. Deterministic from // the filename alone — no git history, so it holds on shallow CI checkouts. -const DATED = /(\d{4}-\d{2}-\d{2})-[^/]*\.md$/ +const DATED = /(?:^|\/)(\d{4}-\d{2}-\d{2})-[^/]*\.md$/ for (const source of sources) { if (isExcluded(source)) continue const dated = DATED.exec(source)