docs(i18n): address terminology review findings
This commit is contained in:
xjt
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
|
||||
2026-07-05-uniform-agent-note-format.md: 06082251c1b96c90ed470d84224662e00e29791b
|
||||
2026-07-05-uniform-agent-note-format.zh.md: a13c436a3fa157a0bfe551a7ed0594d052a4de90
|
||||
2026-07-05-uniform-agent-note-format.zh.md: 3daa686b64b31ee2638b25dd4c42e5d8172f1d97
|
||||
|
||||
@@ -22,7 +22,7 @@ Agent Note 的路径编码了生命周期和类别，但文件内容仍混杂着
|
||||
- **带日期的 Status**（`Status: implemented (accepted YYYY-MM-DD)`）：否决。接受日期属于叙述性历史，写作规则将其排除在文档之外；文件名承载首次提出日期，git 承载其余信息；门禁能检查日期格式，但永远无法检查其真实性。
|
||||
- **裸 `# <title>` H1**：否决。文件脱离目录树单独阅读时，`Agent Note: ` 前缀能自描述其体裁，而格式门禁可防止它漂移。
|
||||
- **以 `## What we give up` 作为已实现记录的结尾**（README 对 Agent Note 所记录内容的原有表述）：否决。它只点出成本，而诚实的后果章节也会记录取舍换来了什么。
|
||||
- **只有约定没有门禁**（写下约定，靠评审强制执行）：否决。slop checklist 已经通过约定禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠约定在此处能达到什么效果。
|
||||
- **只有惯例没有门禁**（写下约定，靠评审强制执行）：否决。slop checklist 已经通过惯例禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠惯例在此处能达到什么效果。
|
||||
- **独立的 `FORMAT.md` 约定文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个约定文件更易发现和维护。
|
||||
|
||||
## 后果
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
|
||||
2026-07-12-package-model-experience-contract.md: 92a8e5a1a81d00dae085e4af89456896373058e6
|
||||
2026-07-12-package-model-experience-contract.zh.md: 9fb6e36e75dcca43fd3ed450c364c57ae7fb7ca4
|
||||
2026-07-12-package-model-experience-contract.zh.md: ded8c9fd940b986d9b37ad1563060b8b96e966bb
|
||||
|
||||
@@ -26,7 +26,7 @@ Status: implemented
|
||||
- **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
|
||||
- **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
|
||||
- **要求经审计的零效应包或简单间接包使用完整结构化格式**：否决。它会围绕一个事实重复标签。受门禁约束的句子加 cache 字段既保留显式覆盖，又没有多余仪式。
|
||||
- **只有约定而无门禁**：否决。仓库级约定必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
|
||||
- **只有惯例而无门禁**：否决。仓库级约定必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
|
||||
|
||||
## 后果
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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 .agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md
|
||||
2026-08-09-chinese-contract-terminology.md: d2fea45c6864a19b89c78a52f614ccac341a0127
|
||||
2026-08-09-chinese-contract-terminology.zh.md: 772b78daba00c5d881fd0091951557dfc0951ee9
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: Standardize Chinese contract terminology on 约定
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-09-chinese-contract-terminology.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The Chinese documentation rendered English `contract` inconsistently as `契约` and `约定`, sometimes within one file or paragraph. The terminology table prescribed `契约`, while reviewed incremental proofreading selected the more natural engineering rendering `约定`. Leaving the table and corpus split made either choice fail the repository's terminology rule and allowed later translations to reintroduce the disagreement.
|
||||
|
||||
English `convention` also commonly renders as `约定`. That overlap is intentional: ordinary Chinese engineering prose uses `约定` for both concepts, and context normally carries whether a statement is descriptive practice or a binding interface rule. Where an English sentence explicitly contrasts a convention with a contract, the Chinese sentence must preserve the distinction through wording such as `惯例` versus `约定`, rather than mechanically giving every `convention` the same rendering.
|
||||
|
||||
## Decision
|
||||
|
||||
The terminology source of truth defines `contract` as `约定` and `adapter contract` as `适配器约定（adapter contract）` on first mention. Every active Chinese documentation pair follows that ruling; archived Agent Notes remain frozen. Unpaired bilingual calibration assets and the translation prompt's explanatory prose follow the same terms so they cannot teach the superseded rendering.
|
||||
|
||||
The migration is semantic prose maintenance, not a rename of identifiers. Inline code, file paths, links, API names, English filenames containing `contract`, and machine-readable values remain unchanged. `convention` does not receive a global terminology row or corpus-wide rewrite: translators preserve natural Chinese and explicitly disambiguate only where the source contrasts the two concepts.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep `contract` as `契约`.** Rejected because the reviewed corpus consistently preferred `约定` for technical interfaces, lifecycle guarantees, and behavioral boundaries, and maintaining the older term would require reverting accepted proofreading across many documents.
|
||||
|
||||
**Give `convention` a mandatory global rendering.** Rejected because its meaning ranges from naming practice to protocol convention. A single forced term would create a second broad migration without improving ordinary prose; only explicit source contrasts require a distinct rendering.
|
||||
|
||||
**Permit both `契约` and `约定` for `contract`.** Rejected because it preserves the exact inconsistency that made package families and even individual paragraphs disagree.
|
||||
|
||||
## Consequences
|
||||
|
||||
Active Chinese documentation has one binding rendering for `contract`, and future translation prompts receive that decision directly from the terminology table. Archived records keep their historical text. A source sentence that contrasts convention and contract requires local semantic wording, so equal Chinese dictionary choices never erase a distinction the source actually uses.
|
||||
|
||||
## Verification
|
||||
|
||||
The migration scans every active bilingual pair, updates each affected Chinese document, re-records its pairing sidecar, and leaves active prose with no `契约` occurrences. The pairing gate, full `doc-sync`, website build, translation prompt tests and snapshot, and `git diff --check` verify the resulting corpus and pipeline assets.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: 将中文 contract 术语统一为「约定」
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-09-chinese-contract-terminology.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
中文文档对英文 `contract` 的译法在「契约」与「约定」之间不一致，有时甚至出现在同一文件或段落中。术语表规定使用「契约」，而经过评审的增量复校选择了更符合工程语境的「约定」。若术语表与语料继续分裂，无论选择哪一种译法都会违反仓库术语规则，后续翻译也会再次引入分歧。
|
||||
|
||||
英文 `convention` 也常译为「约定」。这种重合是有意保留的：普通中文工程文体会用「约定」表达这两个概念，通常可由上下文判断它描述的是惯常做法还是有约束力的接口规则。如果英文句子明确对比 convention 与 contract，中文必须通过「惯例」与「约定」等措辞保留这种区分，而不能机械地把每个 `convention` 都译成同一个词。
|
||||
|
||||
## 决策
|
||||
|
||||
术语真源规定 `contract` 译为「约定」，`adapter contract` 首次出现时写作「适配器约定（adapter contract）」。所有活跃中文文档配对均遵循该裁决；归档 Agent Note 保持冻结。未参与配对的双语校准资产和翻译提示词说明文字也采用相同术语，避免继续教授已被取代的译法。
|
||||
|
||||
这次迁移只维护语义正文，不重命名标识符。行内代码、文件路径、链接、API 名称、文件名中包含的英文 `contract` 以及机器可读值均保持不变。`convention` 不新增全局术语行，也不做全语料改写：翻译时保留自然中文，只在源文明确对比两个概念时消歧。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**继续把 `contract` 译为「契约」。** 否决，因为经过评审的语料在技术接口、生命周期保证和行为边界中一致倾向使用「约定」；保留旧术语意味着回退大量已接受的复校结果。
|
||||
|
||||
**为 `convention` 规定强制的全局译法。** 否决，因为它既可表示命名惯例，也可表示协议约定。强制一种译法会带来另一轮大规模迁移，却无法改善普通行文；只有源文明示对比时才需要使用不同措辞。
|
||||
|
||||
**允许 `contract` 同时使用「契约」与「约定」。** 否决，因为这会保留导致包家族乃至同一段落互相矛盾的原始问题。
|
||||
|
||||
## 后果
|
||||
|
||||
活跃中文文档对 `contract` 只有一种有约束力的译法，后续翻译提示词会直接从术语表获得该决定。归档记录保留历史文字。源文若对比 convention 与 contract，仍需在局部使用语义化措辞，因此相同的常用中文译法不会抹去源文真正表达的区别。
|
||||
|
||||
## 验证
|
||||
|
||||
迁移扫描每一组活跃双语配对，更新受影响的中文文档并重新记录对应 sidecar，使活跃正文不再出现「契约」。配对门禁、完整 `doc-sync`、网站构建、翻译提示词测试与快照，以及 `git diff --check` 共同验证最终语料和流水线资产。
|
||||
Reference in New Issue
Block a user