術語表

術語表檔案可以確保翻譯用詞一致。定義特定詞彙該如何翻譯——或保持原文不翻——yaku 會將這些規則注入 LLM 提示詞中。

快速開始

在工作目錄中建立 .yaku-glossary.yaml 檔案：

.yaku-glossary.yaml

zh-TW:
  arrow function: 箭頭函式     # 固定翻譯
  arrow key: 方向鍵
  Kubernetes: ~               # 保持原文
  Docker: ~                   # 保持原文

照常翻譯即可。yaku 會自動載入術語表：

yaku --to zh-TW -f docs.en.md

LLM 會收到類似這樣的指示：

• 「使用以下指定翻譯：arrow function → 箭頭函式、arrow key → 方向鍵」
• 「保持以下詞彙的原文（不要翻譯）：Kubernetes、Docker」

檔案格式

術語表使用 YAML 格式。詞彙依目標語言代碼分組：

<target-language>:
  <term>: <translation>     # 翻譯為指定值
  <term>: ~                 # 保持原文（YAML null）

一個檔案中可以包含多種語言的區段：

zh-TW:
  container: 容器
  Kubernetes: ~

ja:
  container: コンテナ
  Kubernetes: ~

yaku 只會載入與 --to 目標語言匹配的區段（不區分大小寫）。例如 --to zh-TW 會匹配 zh-TW:、zh-tw: 或 ZH-TW:。如果沒有匹配的區段，yaku 會使用空術語表。

翻譯項目

提供字串值來定義詞彙的翻譯方式：

zh-TW:
  arrow function: 箭頭函式
  database: 資料庫
  machine learning: 機器學習

當 yaku 翻譯到 zh-TW 時，會將這些詞彙作為指定翻譯注入 LLM 提示詞。

保持原文項目

使用 ~（YAML null）告訴 yaku 保持詞彙原文不變：

zh-TW:
  Kubernetes: ~
  Docker: ~
  API: ~
  GitHub: ~

這對品牌名稱、專有名詞，以及翻譯時不應更動的技術用語特別有用。

檔案查找

使用 --glossary <path> 時，yaku 只載入該檔案。否則 yaku 會檢查兩個預設位置，並合併它們（後面檔案的詞彙會覆蓋前面的）：

1. ~/.config/yaku/glossary.yaml — 跨專案共用的全域詞彙（最先載入）
2. .yaku-glossary.yaml（位於當前工作目錄）— 專案專屬詞彙（最後載入，優先使用）

兩個檔案都存在時都會被載入。當同一詞彙同時出現在兩個檔案中，專案檔案優先。

要完全跳過術語表載入：

yaku --to zh-TW --no-glossary -f docs.en.md

範例：專案術語表 + 全域術語表

設定全域術語表來保護不應更動的品牌名稱：

~/.config/yaku/glossary.yaml

zh-TW:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

ja:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

再為各專案加上專屬詞彙：

/path/to/my-project/.yaku-glossary.yaml

zh-TW:
  container: 容器
  deployment: 部署
  service: 服務

在 /path/to/my-project/ 目錄下執行 yaku --to zh-TW 時，兩個檔案都會被載入。全域術語表保持品牌名稱不變，專案術語表統一領域用語。

明確指定術語表路徑

yaku --to zh-TW --glossary ~/work/shared-terms.yaml -f docs.en.md

使用 --glossary 時，只會載入該檔案——預設路徑會被跳過。

運作原理

1. 載入 — yaku 讀取術語表檔案，查找 --to 語言對應的區段。
2. 注入 — 翻譯項目變成 「使用以下指定翻譯：arrow function → 箭頭函式」。保持原文項目變成 「保持以下詞彙的原文：Kubernetes、Docker」。
3. 翻譯 — LLM 在翻譯文字時會看到術語表指示。
4. 驗證 — 翻譯完成後，yaku 會執行安全檢查（EnforceKeepOriginal），確認標記為 ~ 的詞彙仍保留在輸出中。這是安全網——主要的術語控制透過提示詞實現。

提示詞注入的方式使術語表適用於所有後端（Gemini、OpenAI、Anthropic、託管服務）和所有格式（純文字、Markdown、JSON、YAML）。

完整範例：翻譯美食部落格

.yaku-glossary.yaml

zh-TW:
  # 保持料理名稱原文
  ratatouille: ~
  croissant: ~
  miso: ~
  dashi: ~

  # 統一烹飪用語
  sauté: 嫩煎
  arrow root: 葛粉
  mise en place: 備料

ja:
  ratatouille: ~
  croissant: ~
  sauté: ソテー
  mise en place: ミザンプラス

yaku --to zh-TW -f recipe.en.md -o recipe.zh-TW.md

何時使用術語表

• 開源專案 — 確保品牌名稱和技術用語在各語言翻譯中保持一致。
• 文件網站 — 統一標準用語（例如：永遠將「container」翻譯為「容器」）。
• 法規產業 — 鎖定法律或醫學用語的翻譯。
• 多人翻譯流程 — 確保每個人使用相同的詞彙。

小技巧

• 從小處開始。 發現不一致時再加入詞彙。10–20 個詞彙足以涵蓋大多數專案。
• 品牌名稱用 ~。 「GitHub」、「Kubernetes」、「Docker」這類詞彙幾乎永遠不該被翻譯。
• 通用詞彙放全域術語表。 將品牌名稱和常見技術用語放在 ~/.config/yaku/glossary.yaml，讓它們套用到所有專案。
• 專案術語表放在工作目錄。 yaku 會在執行指令的目錄中尋找 .yaku-glossary.yaml。
• 搭配 --context 使用。 術語表處理特定詞彙；--context 設定整體語氣和領域。