OpenCode 繁體中文術語表解析：zh-tw i18n 翻譯規範與自動同步機制

本文以 OpenCode 仓库中的繁體中文（Traditional Chinese）本地化術語表 zh-tw.md 为主体，完整讲解其中「不翻譯清單」、推薦術語映射、文風指引與禁忌規則；並結合 translate-app.ts 自動化翻譯腳本與 translate-app.md 提示詞模板，展示這份術語表如何被真實注入翻譯流水線、如何與英文源字典做漂移檢測，使讀者既能掌握繁中 i18n 的標準譯法，也能理解 OpenCode 多語言詞表同步的完整工程鏈路。

術語表在 OpenCode i18n 體系中的定位

OpenCode 的本地化採用「全局術語表 + 各語言術語表」兩層結構。glossary 目錄說明 明確指出：全局術語表是共享「不翻譯」條目（命令、代碼、路徑、產品名等）的權威來源，而 .opencode/glossary/ 下的每個語言文件則記錄該語言社區在措辭與術語偏好上沉淀的經驗。

該目錄下共維護了 ar、br、bs、da、de、es、fr、ja、ko、no、pl、ru、th、tr、zh-cn、zh-tw 等十餘個語言術語表。文件命名遵循兩條規則（見 glossary README）：

• 每個語言一個文件，使用小寫 locale slug，與文檔語言代碼保持一致（例如 zh-cn.md、zh-tw.md）；
• 若倉庫內部 slug 與標準 BCP47 代碼不一致（別名），則在該文件的 Guidance 中說明。本文主角 zh-tw.md 正屬於此類：產品代碼中繁體中文的 locale 代碼是 zht（見 desktop-native.ts 中 DESKTOP_NATIVE_LOCALES 與 DESKTOP_NATIVE_LABELS 的 zht: "繁體中文" 定義），而術語表文件名使用 zh-tw.md。這一別名映射在翻譯腳本中有顯式處理，下文會具體說明。

zh-tw 術語表完整內容

來源（Sources）

原文檔將本術語表的規則溯源到一個具體的社區貢獻——PR #13942（該 PR 將繁體中文文案整體調整為更自然、直接的語氣）。術語表要求每新增一條規則都要同步更新 Sources 區塊，這是 glossary README 中「Contribution Notes」明確規定的貢獻慣例，目的是讓每一條譯法都有可查證的社區討論背書，而非個人臆造。

不翻譯清單（Locale Additions）

以下條目在繁中語境中必須保持英文原文與原始大小寫：

條目	規則
OpenCode	正文中保留大小寫；僅當 opencode 是命令、包名、路徑或代碼的一部分時才寫成小寫
OpenCode Zen	產品名，整體保留
OpenCode CLI	產品名，整體保留
CLI、TUI、MCP、OAuth	縮寫保留英文
Model Context Protocol	首次引出 MCP 時優先用英文全稱

這組規則與全局術語表互補：全局表管「命令、代碼、路徑、產品名」等通用不翻譯項，locale 文件只補充「該語言特有的大小寫與措辭決策」。

推薦術語（Preferred Terms）

原文檔給出了九組英文 → 繁中推薦術語映射，並特別註明這些術語「可能隨時間演進」（may evolve），即屬於「preferred」而非強制標準：

English	Preferred	Notes
prompt	提示詞	標誌參數與代碼中的 --prompt 保持不變
session	工作階段
provider	供應商
share link / shared URL	分享連結	面向用戶的分享動作優先用 分享
headless (server)	無介面	文檔措辭
authentication	認證	認證 / OAuth 語境下優先
cache	快取
keybind / shortcut	快捷鍵	面向用戶文檔措辭
workflow	工作流程	例如 GitHub Actions workflow

值得注意的是「技術產物精確保留」原則在術語表中就已有體現：prompt 譯作「提示詞」，但命令行旗標 --prompt 絕不翻譯。這一原則在自動化提示詞模板中再次被強化（見下一節）。

文風指引（Guidance）與禁忌（Avoid）

術語表後半部分給出了四條文風指引與兩條禁忌，這直接決定了繁中界面文案的語感：

Guidance：

• 優先自然、簡練的措辭，而非逐字直譯；
• 語氣保持直接而親切——PR #13942 的調整方向一致；
• 技術產物精確保留：命令、旗標、代碼、行內代碼、URL、文件路徑、模型 ID 一律原樣；
• 枚舉型字面量（如 default、json）在作為字面值出現時保持英文；
• 同一術語一旦確立（如 工作階段、供應商、提示詞），所有頁面保持一致。

Avoid：

• 正文中用產品名時避免 opencode（小寫），應使用 OpenCode；
• 已有推薦術語時，避免在同一概念上混用別譯。

術語表如何被翻譯流水線消費

zh-tw.md 並非孤立的文檔，它被 OpenCode 的應用翻譯自動化腳本直接讀取並注入到 AI 翻譯提示詞中。整條鏈路如下。

locale 別名映射：zht → zh-tw.md

translate-app.ts 中的 glossaryFile() 承擔術語表文件的解析：

export function glossaryFile(locale: Locale) {
  if (locale === "zh") return ".opencode/glossary/zh-cn.md"
  if (locale === "zht") return ".opencode/glossary/zh-tw.md"
  return `.opencode/glossary/${locale}.md`
}

即：當翻譯目標語言為 zht（產品代碼中的繁體中文代碼）時，腳本自動定位到本術語表。這也解釋了為什麼術語表文件名與代碼 locale 代碼不一致——別名在腳本層被規整。

術語表注入提示詞

翻譯時，腳本在 translate() 函數 中讀取術語表全文，與 locale、語言名、源/目標文件、漂移清單一併打包成 JSON，填入 translate-app.md 模板的 $ARGUMENTS 占位符。模板要求：

• 英文是唯讀源，任何英文 key/value 都視爲有意設計，不得修改；
• 補齊所有缺失 key、移除多餘 key、修復占位符不匹配的 value；
• 精確保留 OpenCode、API 名、標識符、代碼、命令、旗標、路徑、URL、版本、錯誤訊息、配置鍵與 {{tokens}} 占位符——與術語表「技術產物精確保留」一脈相承；
• 開發者術語要「使用目標語言開發者社區已認可的用語」而非字典直譯，並要求至少核對 Firefox、KDE、VS Code 中兩種維護中的本地化語料庫；
• 對 session、prompt、agent、model、provider 等高頻概念保持全篇一致——這正是術語表中 工作階段/供應商/提示詞 等條目存在的意義；
• 「應用請求中附帶的 locale 術語表」（Apply the locale glossary included in the request）——zh-tw.md 的內容在此被明確要求落實。

隔離配置與權限收斂

每次翻譯運行都以獨立環境啟動，translationConfig() 生成的配置關閉了 share、formatter、LSP、snapshot，並通過權限矩陣只放開 read、glob、grep、webfetch、websearch 與「目標文件列表內的 edit」，其他一切 edit 一律 deny。這確保 AI 只可能改動 packages/app/src/i18n/zht.ts 一類本語言詞表文件（文件集由 targetFiles() 確定，涵蓋 app、ui、desktop 三個域）。翻譯結束後，腳本還會用 git worktree 快照比對，若出現目標文件之外的變更則直接判失敗（unexpectedChanges()，見 L224-L229）。

漂移檢測：術語表規則的機械化兜底

術語表管「譯得對不對」，而 findDrift() 管「同步得全不全」。它以英文字典為源、目標語言字典為靶，報告三類問題：

• missing：源字典有、目標字典缺的 key（含按 CLDR 複數範疇展開的派生 key）；
• extra：目標字典多出的 key；
• placeholders：{{token}} 占位符與英文不一致的 key（占位符提取邏輯 tokens() 見 L578-L580）。

--check 模式只報告漂移並以此決定退出碼，適合放入 CI 作守門。

實際運行方式

在倉庫根目錄（package.json 中註冊了 translate:app 腳本）：

# 同步繁體中文詞表（zht → app/ui/desktop 三個域）
bun run translate:app -- zht

# 僅檢查漂移，不觸發翻譯
bun run translate:app -- zht --check

# 並行翻譯全部語言
bun run translate:app -- all --concurrency 4

可用參數（見 parseTranslationArgs() 與 help 輸出）：

參數	說明
<locale|all>（位置參數）	目標語言代碼或 all，單語言時並發強制為 1
-c, --concurrency <n>	all 模式下最大的 OpenCode 並行數，默認 4
--model <provider/id>	使用的模型，默認 opencode/gpt-5.5
--variant <name>	模型變體，默認 xhigh；腳本會先通過 opencode models 校驗該變體確實存在
--dry-run	只報告漂移，不運行 OpenCode
--check	存在漂移時以非零退出碼結束

此外，倉庫還提供了一個交互式的 translate 命令（.opencode/command/translate.md），用於對 git diff 中變動的英文文檔/UI 文案做多語言同步，它同樣要求「應用 .opencode/glossary/<locale>.md（如 zh-cn.md）的 locale 特定指引」，並同樣遵守不翻譯清單。兩條路徑共同保證 zh-tw.md 的规则在全倉翻譯場景中生效。

術語表文件本身的結構與擴展方式

從 zh-tw.md 的骨架可以歸納出 glossary README 定義的標準五段結構：Sources → Do Not Translate (Locale Additions) → Preferred Terms → Guidance → Avoid（可選）。README 還給出了完整模板與收錄準則：優先收錄「在多頁/多界面重複出現、易於一致應用、且有社區貢獻或審查討論背書」的指引；新規則應先寫「preferred」標記（表示可能演進）；若尚無術語級糾正，可先給通用指引。

對繁中而言，這份術語表的工程價值在於：它把「提示詞 / 工作階段 / 供應商 / 分享連結 / 無介面 / 認證 / 快取 / 快捷鍵 / 工作流程」九組高頻術語固定為全倉一致譯法，同時以「不翻譯清單 + 技術產物精確保留」約束住產品名、縮寫與字面量，並被 translate:app 腳本机械化注入到每次 AI 翻譯請求中——術語規範從「人讀的文檔」變成了「流水線的輸入」，這是 OpenCode 多語言詞表能長期保持一致性、可漂移檢測的基礎。

相關深入閱讀：

• glossary README（術語表體系說明與模板）
• 翻譯腳本主實現
• AI 翻譯提示詞模板
• 繁中詞表字典
• locale 註冊與複數範疇
• 語言合併入口