深入解析 opencode 自定义命令 /translate：构建可复现的多语言翻译工作流

opencode（The open source coding agent）仓库自带一套存放在 .opencode/command/ 目录下的自定义命令，其中 translate.md 专门负责把仓库内变更过的英文文档与 UI 文案批量翻译到其他语言。本文以该命令文件为主体，完整解读它的配置项、翻译约束与配套词表（Glossary）体系，并结合仓库中的 i18n 字典文件与批量翻译脚本，说明这套"命令驱动的多语言同步"工作流的完整调用链，读完后可在同类项目中复刻一条从 git diff 到多语言落地的自动翻译流水线。

一、translate.md 全文解读：一个命令文件由什么构成

.opencode/command/translate.md 是 opencode 的自定义命令定义文件，采用"YAML frontmatter + 提示词正文"的结构。完整内容如下（逐行继承自原文档）：

---
description: translate English to other languages
model: opencode/gpt-5.6-sol
---

run git diff and translate changed english doc and UI copy files to other international languages. Translate all languages in parallel to save time.

Requirements:

- Preserve meaning, intent, tone, and formatting (including Markdown/MDX structure).
- Preserve all technical terms and artifacts exactly: product/company names, API names, identifiers, code, commands/flags, file paths, URLs, versions, error messages, config keys/values, and anything inside inline code or code blocks.
- Also preserve every term listed in the Do-Not-Translate glossary below.
- Also apply locale-specific guidance from `.opencode/glossary/<locale>.md` when available (for example, `zh-cn.md`).
- Do not modify fenced code blocks.

1.1 frontmatter：声明命令的元信息

命令文件的 frontmatter 承载两类元信息：

• description: translate English to other languages —— 命令用途的一句话说明，用于在命令列表中展示、帮助 Agent 判断该命令的适用场景；
• model: opencode/gpt-5.6-sol —— 为这条命令固定了执行所用的模型。对比同目录下的其他命令可以看到这是每个命令可独立声明的字段：changelog.md 使用 model: opencode/gpt-5.4，commit.md 使用 model: opencode/kimi-k2.5 并额外声明了 subtask: true。也就是说，opencode 允许为不同任务（写 changelog、提交代码、翻译文案）分别绑定不同能力定位的模型，而 translate 命令选择了 opencode/gpt-5.6-sol 这一模型标识。

1.2 正文：给 Agent 的任务指令

正文第一段就是核心指令："run git diff and translate changed english doc and UI copy files to other international languages. Translate all languages in parallel to save time."，可以拆出三个关键行为约束：

1. 翻译范围以 git diff 为界：不是全量重翻，而是只处理"发生变更"的英文文档与 UI 文案文件。这使命令可以挂在开发流程中频繁执行，增量翻译的成本与改动量成正比；
2. 目标是多语言：同一批变更需要落到多个目标语言；
3. 并行执行：明确要求把所有语言的翻译并行处理以节省时间——在 opencode 的 TUI 中，这对应同时发起多条翻译会话/子任务的使用方式。

二、五条 Requirements 逐条剖析：翻译质量的契约

命令正文的 Requirements 列表是这条命令真正的"验收标准"，本质上是写给执行 Agent 的强约束契约。逐条来看：

1. 保留语义、意图、语气与格式（含 Markdown/MDX 结构）

翻译必须逐层保真：先保语义与语气，再保文档结构。opencode 的文档体系大量使用 MDX（例如 packages/web/src/ 下的 .mdx 文件、packages/docs/ 下的文档站点源码），因此格式保留不仅是排版问题，还涉及 MDX 组件标记不被破坏，否则文档站点构建会失败。

2. 技术制品逐字保留（Do-not-modify 清单）

这条列出了必须原样保留的完整清单：

• 产品/公司名、API 名、标识符；
• 代码、命令/参数标志（flags）、文件路径、URL、版本号、错误信息；
• 配置键值对（config keys/values）；
• 任何位于行内代码或代码块中的内容。

这一清单与 script/translate-app.md 中的同类约束高度一致（"Preserve technical terms and artifacts exactly: OpenCode, API names, identifiers, code, commands, flags, paths, URLs, versions, error messages, config keys, and placeholder tokens"），可见它是 opencode 仓库翻译工作的全局惯例，而非单条命令的临时要求。

3. 保留 Do-Not-Translate 词表中的全部词条

命令引用了一份"禁止翻译词表"作为补充约束（见第三节 glossary 体系），保证品牌词、协议缩写等在全仓库范围内的一致处理。

4. 应用 locale 专属指南：.opencode/glossary/<locale>.md

这是 translate 命令与其他通用翻译提示最大的差异点：它把每种语言的本地化经验外置成了独立文件，按 <locale>.md 命名存放于 .opencode/glossary/ 目录，并在翻译对应语言时按需加载（命令举例 zh-cn.md）。目前仓库中已有的 locale 文件包括：ar.md、br.md、bs.md、da.md、de.md、es.md、fr.md、ja.md、ko.md、no.md、pl.md、ru.md、th.md、tr.md、zh-cn.md、zh-tw.md。

5. 不修改围栏代码块（fenced code blocks）

即使代码块内存在英文注释说明，也不得改动——代码块视为不可变区域，与第 2 条的"代码逐字保留"形成双重保障，避免 Agent 在"翻译文档"时误伤示例代码。

三、Glossary 体系：locale 词表文件的规范与实例

3.1 词表目录的规范（README 约定）

.opencode/glossary/README.md 定义了词表文件的组织规范，是理解 translate 命令第 4 条要求的关键：

• 文件命名：每个 locale 一个文件，使用小写 locale slug，尽量与文档站点使用的 locale 一致（如 zh-cn.md、zh-tw.md）；若只有语言级指南则直接用语言代码（如 fr.md）；仓库中允许存在别名 slug（例如 br 对应巴西葡萄牙语 / pt-BR），别名需在文件的 Guidance 小节中说明；
• 内容结构（README 给出的模板）：每个 locale 文件应包含 Sources（驱动该指南的 PR/issue）、Do Not Translate (Locale Additions)（locale 专属禁翻词条与大小写决定）、Preferred Terms（推荐术语表）、Guidance（语气与风格指引）、Avoid（应避免的字面直译）；
• 准入标准：优先收录跨多篇文档/界面反复出现、易于一致执行、且有社区贡献或评审讨论支撑的指南；
• 维护原则：新术语映射优先来自已合并 PR（"Prefer PR-backed guidance over invented term mappings"），尚无术语级修正时先给通用指南，可演进的条目标记为 preferred。

需要说明的是：README 声明"全局词表（translator.md）是共享禁翻词条的 source of truth"，但在当前仓库目录树中 .opencode/agent/ 下实际只有 duplicate-pr.md 与 triage.md 两个文件，未见到 translator.md，因此当前共享禁翻约束实际承载在命令 Requirements 本身与各 locale 文件的 "Do Not Translate" 小节中。

3.2 实例：zh-cn.md 如何约束中文翻译

以 zh-cn.md 为例，它完整呈现了上述模板的落地形态：

Do Not Translate（locale 专属）：

• OpenCode（正文中保留大小写；仅当 opencode 是命令、包名、路径或代码的一部分时才保留小写）；
• OpenCode Zen、OpenCode CLI；
• CLI、TUI、MCP、OAuth 等缩写；
• 首次引入 MCP 时优先使用英文全称 Model Context Protocol。

Preferred Terms（推荐术语表，节选）：

English	Preferred	Notes
prompt	提示词	--prompt 等 flag/代码中保持不变
session	会话
provider	提供商
share link / shared URL	分享链接	面向用户的分享动作优先用 分享
headless (server)	无界面	文档用词
authentication	认证	auth/OAuth 语境下优先
cache	缓存
keybind / shortcut	快捷键	面向用户的文档用词
workflow	工作流	例如 GitHub Actions workflow

Guidance / Avoid（风格与禁忌）：

• 优先自然、简洁的表达，避免字面直译；语气直接而友好；
• 命令、flag、代码、行内代码、URL、文件路径、模型 ID 等技术制品逐字保留；
• 枚举式字面量（如 default、json）在作为字面取值时保持英文；
• 术语一经选定须跨页面一致（会话、提供商、提示词 等）；
• 禁忌：正文指代产品名时避免用小写 opencode，应使用 OpenCode；避免同一概念在已确立推荐术语后仍混用多个译名。

这套"命令中的硬约束 + locale 词表中的软指南"双层设计，使 translate 命令既能保证底线（不翻代码、不翻产品名），又能持续吸收每个语言社区的评审经验，而词表本身又是纯 Markdown，可直接被 Agent 读取与更新。

四、翻译目标从哪里来：仓库中的英文源与 i18n 字典

translate 命令说"translate changed english doc and UI copy files"，仓库中对应的英文源与目标落点主要有两类，结合仓库结构可以印证命令的翻译对象：

1. 英文文档：仓库根目录下的 README.md 以及各语言版本（README.zh.md、README.ja.md、README.de.md、README.fr.md 等十余个语言文件），还有 packages/docs/ 下的 MDX 文档。英文 README 是 source of truth，各语言 README 是翻译落点——这与"git diff 中变更的英文文档"的描述完全对应：当 README.md 或 docs 内容改动后，运行 translate 命令即增量同步各语言版本。

2. UI 文案（i18n 字典）：应用层的 UI 字符串集中在 packages/app/src/i18n/ 目录，按 locale 拆分为 60 余个 .ts 字典文件（en.ts、zh.ts、zht.ts、ja.ts、ko.ts、de.ts、fr.ts 等）。以 en.ts 为例，其内容形如：

export const dict = {
  ...DESKTOP_NATIVE_ENGLISH,
  "command.category.suggested": "Suggested",
  "command.category.view": "View",
  // ...
  "command.session.previous.unseen": "Previous unread session",
  "command.session.archive": "Archive session",
}

可以看到字典采用 key: string 结构，key 是稳定标识符（永不翻译），value 是可本地化文案，且支持 {{index}} 这类插值占位符（如 "command.project.index": "Switch to project {{index}}"）。翻译此类文件时的核心风险正是占位符与 key 的破坏，这也是 Requirements 中反复强调"保留 identifiers、config keys/values 与行内代码"的原因。

五、配套的批量翻译脚本 translate-app.ts：从增量命令到全量校验

仓库中还有一条与 translate 命令互补的自动化链路：script/translate-app.ts（npm script 名为 translate:app，见 package.json 中 "translate:app": "bun run script/translate-app.ts"），用于把产品应用层 locale 从英文源字典做全量同步与漂移检测，并把生成的"翻译请求"交给 script/translate-app.md 定义的提示词执行。

从 script/translate-app.ts 的参数解析（L86-L115）可以看到它支持的完整参数集：

参数	短选项	默认值	说明
位置参数（locale 或 all）	—	all	目标 locale，必须是已知 locale，一次只能传一个
--concurrency	-c	4	并发数；指定单一 locale 时强制为 1
--model	—	opencode/gpt-5.5	执行翻译的模型
--variant	—	xhigh	推理强度档位
--dry-run	—	false	只检查不写入
--check	—	false	校验模式，CI 场景用于确认无漂移
--help	-h	false	帮助

脚本中 targetFiles(locale)（L117 起）给出的目标文件为 packages/app/src/i18n/<locale>.ts 与 packages/ui/src/i18n/<locale>.ts，即应用与 UI 两个包的字典文件；它对照英文源字典计算出 missing（缺失 key）、extra（多余 key）与 placeholders（占位符不匹配）三类漂移，连同 locale 词表一起打包进翻译请求。配套的 script/translate-app.md 提示词则规定了执行纪律：英文字典是只读 source of truth、只能编辑请求中列出的目标文件、占位符 {{tokens}} 必须与英文精确对齐、受限使用 read/glob/grep/edit 等工具、"直到所有请求的 key 全部同步且没有其他文件变化才算完成"。

对照两条链路可以看到清晰的分工：.opencode/command/translate.md 面向"变更触发"的增量翻译（git diff 驱动、多语言并行、依赖 glossary 词表），script/translate-app.ts 面向"状态对齐"的全量翻译与 CI 校验（漂移检测、dry-run/check 模式）。二者共享同一套"英文只读、技术制品不动、占位符精确、术语表驱动"的原则，构成了 opencode 仓库多语言维护的完整闭环。

六、实战使用方式与可复现要点

在当前仓库中，使用 translate 命令的完整方式是：在 opencode 会话中触发 /translate 命令（opencode 会把 .opencode/command/translate.md 的 frontmatter + 正文组装为提示词交给指定模型 opencode/gpt-5.6-sol），命令执行时 Agent 会：

1. 运行 git diff 定位变更的英文文档与 UI 文案文件；
2. 对每个受影响语言，读取对应的 .opencode/glossary/.md 词表；
3. 并行发起各语言的翻译，产出严格满足五条 Requirements 的译文（结构保留、代码不动、技术制品逐字、禁翻词表生效）；
4. 落点为对应语言的 README 文件、docs 文档或 i18n 字典文件。

若要在新项目复刻这套工作流，从源码结构看可以归纳为四个可迁移的要点：

• 命令文件 = frontmatter（description + model）+ 任务正文：把"做什么"写成对 Agent 的直接指令，并固定执行模型；同目录的 commit.md、changelog.md 还展示了正文中用 !`command` 语法内联注入命令输出（如 !`git diff`）的用法，translate 命令则选择让 Agent 自行运行 git diff；
• 约束分层：通用硬约束写在命令正文的 Requirements 中，locale 个性化指南外置为独立 Markdown 词表，二者职责清晰、可独立演进；
• 英文为唯一 source of truth：所有链路（translate 命令、translate-app 脚本、translate-app.md 提示词）都声明英文文件只读，翻译只能向各语言方向流动；
• 增量 + 全量双通道：用 diff 驱动的增量命令覆盖日常变更，用带 --check/--dry-run 的全量脚本兜底校验，保证字典漂移（missing/extra/placeholder mismatch）可被检测。

七、小结

.opencode/command/translate.md 虽然篇幅不长，却是 opencode 仓库 i18n 工作流的入口：它用一段带 frontmatter 的提示词，把"git diff 增量检测 → 多语言并行翻译 → glossary 词表约束 → 技术制品零改动"固化为可反复执行的命令。配合 .opencode/glossary/ 下 16 个 locale 词表文件、packages/app/src/i18n/ 下的 60 余个语言字典，以及 script/translate-app.ts 的全量漂移检测链路，共同支撑起一个由 LLM 驱动、但规则可审计、术语可追溯、漂移可校验的多语言维护体系——这也是研究 opencode 这类 coding agent 仓库自身工程化实践时一个典型且完整的样本。