From 50a32cdcb104d98a43966a9b6ef3c17016306cbc Mon Sep 17 00:00:00 2001
From: Ziya <199893125+ZiyaZhang@users.noreply.github.com>
Date: Fri, 3 Jul 2026 02:24:17 -0700
Subject: [PATCH] docs: extend terminology table with i18n mechanism terms
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every new term the bilingual-docs work introduced, with precedented
renderings where precedent exists:

- orphan -> 孤立 (git's official zh l10n renders orphan as 孤立, e.g.
  孤立分支 — not 孤儿; the translations were corrected to match)
- info string -> 信息字符串 (CommonMark zh convention; corrected in the
  i18n README translation)
- fenced code block -> 围栏代码块 (MDN zh), staged -> 暂存 (git zh),
  event-sourced -> 事件溯源 (DDD convention), smoke test -> 冒烟测试,
  fail-fast -> 快速失败, plus fingerprint/pairing/freshness/stale/contract
- mechanism names coined by this repo, marked as such in the notes:
  language switcher -> 语言切换行, structural signature -> 结构签名,
  enforcement frontier -> 强制边界
- keep-English entries so future translators don't guess: backlog,
  blob hash, CI, doc-sync, e2e, monorepo, PR, worktree
---
 docs/i18n/README.zh.md   |  2 +-
 docs/i18n/terminology.md | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index d1ca53f3d8..251a16e984 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -25,7 +25,7 @@
 `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——是翻译批次的工作清单。它从不失败；它只报告。
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index f9baa40adc..2303e43808 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -7,6 +7,7 @@
 | ACP | ACP | 首次出现可写：ACP（Agent Client Protocol） |
 | AI | AI | 首次出现可写：人工智能（AI） |
 | API | API | |
+| CI | CI | |
 | CLI | CLI | 首次出现可写：命令行界面（CLI） |
 | Cordis | Cordis | 保留英文 |
 | Function Calling | Function Calling | 首次出现可写：Function Calling（函数调用） |
@@ -17,16 +18,22 @@
 | 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 loop | agent loop | |
+| backlog | backlog | 双语翻译语境指待翻清单 |
+| blob hash | blob hash | git 对象哈希；`git hash-object` 的结果 |
+| doc-sync | doc-sync | 仓库门禁名，保留英文 |
+| e2e | e2e | |
 | fiber | fiber | 首次出现可写：fiber（插件运行时） |
 | fixture | fixture | 指测试前置数据或环境 |
 | fork | fork | 保留英文 |
 | harness | harness | 保留英文 |
 | manifest | manifest | 描述模块或工具元数据的文件 |
+| monorepo | monorepo | |
 | schema DSL | schema DSL | |
 | schema | schema | 保留英文 |
 | seam | seam | 首次出现可写：seam（扩展点） |
@@ -36,6 +43,7 @@
 | subagent | subagent | 首次出现可写：subagent（子 agent） |
 | transcript | transcript | 首次出现可写：transcript（文本记录）；指会话渲染给用户或编辑器的完整文本，区别于事件日志（event log） |
 | waterfall | waterfall | 首次出现可写：waterfall（瀑布式事件） |
+| worktree | worktree | git 工作区概念，保留英文 |
 | wire format | 协议格式 | 首次出现可写：协议格式（wire format） |
 | adapter contract | 适配器契约 | 首次出现可写：适配器契约（adapter contract） |
 | adapter | 适配器 | |
@@ -54,28 +62,39 @@
 | 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 | 新鲜度 | 指译文相对英文源的同步状态 |
 | hook | 钩子 | |
 | implementation | 实现 | |
 | inference | 推理（inference） | 每次提及时保留英文括注，避免与 reasoning 混淆 |
+| info string | 信息字符串 | CommonMark 中文同译；代码围栏 ``` 之后的语言标注 |
 | injection | 注入 | |
 | interface | 接口 | |
 | integration | 集成 | |
+| language switcher | 语言切换行 | i18n 机制词：双语配对文件顶部的互链行 |
 | memory | memory / 记忆 / 内存 | 按上下文区分：agent memory 译为“记忆”；resource/memory usage 译为“内存” |
 | message | 消息 | |
 | mod | 模组 | 区别于 module（模块）；plugin 译作「插件」 |
 | model provider | 模型提供方 | |
 | module | 模块 | |
+| orphan | 孤立 | git 官方中文同译（如「孤立分支」）；指英文源已不存在的 `.zh.md`；不要译作：孤儿 |
+| pairing | 配对 | |
 | permission | 权限 | |
 | persistence | 持久化 | |
 | pipeline | 流水线 | |
@@ -93,11 +112,15 @@
 | service | 服务 | |
 | session | 会话 | |
 | session event | 会话事件 | |
+| smoke test | 冒烟测试 | |
 | snapshot | 快照 | |
 | spine | 主干 | |
+| staged | 暂存 | git 官方中文同译 |
+| stale | 过期 | 门禁输出保留英文 `stale`，行文译「过期」 |
 | step | 步骤 | |
 | stream | 流 | |
 | streaming | 流式输出 | |
+| structural signature | 结构签名 | i18n 机制词：配对门禁比对的有序结构序列 |
 | system prompt | 系统提示词 | |
 | taxonomy | 分类体系 | |
 | token usage | token 用量 | |