Lightweight routine documentation translation
轻量化日常文档翻译
Routine bilingual edits automatically selected the full [translation skill](../../../skills/dsh-translate-docs/SKILL.md). Even after the [briefed-update optimization](2026-07-26-briefed-minimal-translation-updates.md), a small documentation change could still load a specialized workflow, generate a briefing, delegate prose to a subagent, and perform a separate verification pass. That orchestration consumed more time,
English
Problem
Routine bilingual edits automatically selected the full translation skill. Even after the briefed-update optimization, a small documentation change could still load a specialized workflow, generate a briefing, delegate prose to a subagent, and perform a separate verification pass. That orchestration consumed more time, context, and model tokens than translating the changed text itself, and automatic skill discovery exposed the workflow on ordinary documentation turns.
Decision
- Routine translation is one shot and one pass. The active agent loads terminology.md, translates only the changed content directly, moves a terminology annotation when the true first occurrence crosses the edit boundary, otherwise preserves reviewed counterpart prose outside the change, and re-records the pair. It does not invoke a translation skill, generate a briefing, start a separate translation-review pass, or delegate translation to a subagent.
- The extended workflow is manual-only. dsh-translate-docs retains its briefing, delegated prose, whole-document, and scoped-verification paths. The Claude Code skill contract reads
disable-model-invocation: truewithuser-invocable: trueinSKILL.md; Codex readspolicy.allow_implicit_invocation: falseinagents/openai.yaml. The repository's.claude/skillssymlink projects the same skill directory to Claude Code, so both products share one committed workflow while enforcing their own invocation metadata. Thedoc-syncskill-invocation-metadata gate keeps those independent policies aligned. - Automatic workflows do not chain into the manual skill. Root and documentation instructions own the lightweight default. Documentation, website-sync, prose, and code-review skills link to those instructions or the i18n contracts instead of loading
dsh-translate-docsfrom an inferred bilingual change. - The pairing and review contracts stay intact. Both language files still update together, untouched counterpart wording remains stable, terminology stays binding, the consistency record is rewritten only after the active agent confirms the pair, and
doc-syncretains the corpus-wide mechanical checks. Human review still owns semantic translation quality.
Alternatives considered
- Delete the extended skill and briefing tools — rejected: explicit manual use remains valuable for whole-document translations, difficult reconciliation, and callers that deliberately choose the guarded workflow.
- Replace the extended skill with an automatically invoked lightweight skill — rejected: another automatic skill would still add discovery context and an invocation boundary around a task the active agent can complete directly from the terminology table and standing instructions.
- Keep automatic invocation only for new pairs or large changes — rejected: size-based inference is another hidden policy and can unexpectedly activate the expensive workflow. The user, not the agent, chooses when the extended path is worth its cost.
- Drop the terminology load as well — rejected: the glossary is the small, binding input that prevents repository-wide term drift; removing it would trade token savings for inconsistent product language.
Consequences
- Ordinary development pays for the changed source text, its local counterpart context, and the terminology table rather than the extended workflow's briefing and subagent context.
- The active agent owns the final routine translation in the same turn. The lightweight path deliberately gives up the extended workflow's generated alignment, delegated isolation, and separate prose-verification pass.
- Explicit users can still invoke the full workflow through
/dsh-translate-docsin Claude Code or$dsh-translate-docsin Codex. - The Claude Code frontmatter and Codex policy file are separate product contracts;
doc-syncrejects a skill that becomes manual-only on only one product or becomes unavailable to the Claude Code user as well as the model.
中文
问题
日常双语编辑会自动选用完整的翻译 skill（技能）。即使经过基于简报的更新优化，一次小的文档改动仍可能加载专用工作流、生成简报、把行文翻译委派给 subagent，并另行执行一轮核验。这种编排耗费的时间、上下文和模型 token 比直接翻译改动文本本身还多，而且 skill 的自动发现机制还会在普通文档处理轮次中暴露该工作流。
决策
- 日常翻译一次完成，只处理一遍。 当前 agent（智能体）加载 terminology.md，直接翻译发生改动的内容；如果术语的实际首现位置跨过了编辑边界，则移动相应括注，否则保留改动之外已经评审的对侧文件行文；最后重新记录配对。它不会调用翻译 skill、生成简报、启动单独的翻译评审轮次，也不会把翻译委派给 subagent。
- 扩展工作流仅限手动调用。 dsh-translate-docs 保留简报、行文翻译委派、整篇文档和按范围核验路径。Claude Code skill 契约读取
SKILL.md中的disable-model-invocation: true和user-invocable: true；Codex 读取agents/openai.yaml中的policy.allow_implicit_invocation: false。仓库的.claude/skills符号链接把同一个 skill 目录映射给 Claude Code，因此两个产品共享同一份提交到仓库的工作流，同时分别执行各自的调用元数据契约。doc-sync中的 skill 调用元数据门禁会让这两份独立策略保持一致。 - 自动工作流不会串联调用这项仅限手动调用的 skill。 轻量默认行为由根级指令和文档指令定义。文档、网站同步、行文和代码评审 skill 会链接这些指令或 i18n 契约，而不会因为推断到双语改动就加载
dsh-translate-docs。 - 配对契约与评审契约保持不变。 两种语言文件仍会一并更新；未触及的对侧文件措辞保持稳定；术语约束仍然有效；只有当前 agent 确认配对后，才会重写一致性记录；
doc-sync（文档同步门禁）继续执行全语料机械检查。语义层面的翻译质量仍由人工评审负责。
曾考虑的替代方案
- 删除扩展 skill 和简报工具：不予采纳。在整篇文档翻译或棘手的两侧内容协调中，以及对有意选择受控工作流的调用方而言，显式手动调用仍有价值。
- 用自动调用的轻量 skill 取代扩展 skill：不予采纳。另一项自动 skill 仍会给这项任务增加发现上下文和调用边界，而当前 agent 仅依据术语表与常驻指令即可直接完成该任务。
- 仅对新配对或大规模改动保留自动调用：不予采纳。基于规模的推断同样是一项隐藏政策，可能出乎意料地启用高开销工作流。何时值得为扩展路径付出成本，应由用户而非 agent 决定。
- 同时取消加载术语表：不予采纳。术语表是体量小但有约束力的输入，可以防止整个仓库发生术语漂移；移除它等于用产品语言不一致换取 token 节省。
后果
- 普通开发的成本来自发生改动的源文本、其局部对侧文件上下文和术语表，不再来自扩展工作流的简报与 subagent 上下文。
- 当前 agent 在同一轮次内对日常翻译的最终结果负责。轻量路径有意放弃扩展工作流提供的自动生成对齐信息、委派所提供的隔离，以及单独的行文核验轮次。
- 用户仍可在 Claude Code 中通过
/dsh-translate-docs，或在 Codex 中通过$dsh-translate-docs显式调用完整工作流。 - Claude Code frontmatter 与 Codex 策略文件是彼此独立的产品契约；如果某项 skill 仅在一个产品中变为手动调用，或者在 Claude Code 中对模型和用户都不可用，
doc-sync会拒绝该状态。