术语表

术语表文件可以确保翻译用词一致。定义特定词汇该如何翻译——或保持原文不翻——yaku 会将这些规则注入 LLM 提示词中。

快速开始

在工作目录中创建 .yaku-glossary.yaml 文件：

.yaku-glossary.yaml

zh-CN:
  arrow function: 箭头函数     # 固定翻译
  arrow key: 方向键
  Kubernetes: ~               # 保持原文
  Docker: ~                   # 保持原文

照常翻译即可。yaku 会自动加载术语表：

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

LLM 会收到类似这样的指示：

• “使用以下指定翻译：arrow function → 箭头函数、arrow key → 方向键”
• “保持以下词汇的原文（不要翻译）：Kubernetes、Docker”

文件格式

术语表使用 YAML 格式。词汇依目标语言代码分组：

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

一个文件中可以包含多种语言的区段：

zh-CN:
  container: 容器
  Kubernetes: ~

ja:
  container: コンテナ
  Kubernetes: ~

yaku 只会加载与 --to 目标语言匹配的区段（不区分大小写）。例如 --to zh-CN 会匹配 zh-CN:、zh-cn: 或 ZH-CN:。如果没有匹配的区段，yaku 会使用空术语表。

翻译条目

提供字符串值来定义词汇的翻译方式：

zh-CN:
  arrow function: 箭头函数
  database: 数据库
  machine learning: 机器学习

当 yaku 翻译到 zh-CN 时，会将这些词汇作为指定翻译注入 LLM 提示词。

保持原文条目

使用 ~（YAML null）告诉 yaku 保持词汇原文不变：

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

这对品牌名称、专有名词，以及翻译时不应更动的技术用语特别有用。

文件查找

使用 --glossary <path> 时，yaku 只加载该文件。否则 yaku 会检查两个默认位置，并合并它们（后面文件的词汇会覆盖前面的）：

1. ~/.config/yaku/glossary.yaml — 跨项目共用的全局词汇（最先加载）
2. .yaku-glossary.yaml（位于当前工作目录）— 项目专属词汇（最后加载，优先使用）

两个文件都存在时都会被加载。当同一词汇同时出现在两个文件中，项目文件优先。

要完全跳过术语表加载：

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

示例：项目术语表 + 全局术语表

设置全局术语表来保护不应更动的品牌名称：

~/.config/yaku/glossary.yaml

zh-CN:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

ja:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

再为各项目加上专属词汇：

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

zh-CN:
  container: 容器
  deployment: 部署
  service: 服务

在 /path/to/my-project/ 目录下执行 yaku --to zh-CN 时，两个文件都会被加载。全局术语表保持品牌名称不变，项目术语表统一领域用词。

明确指定术语表路径

yaku --to zh-CN --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-CN:
  # 保持料理名称原文
  ratatouille: ~
  croissant: ~
  miso: ~
  dashi: ~

  # 统一烹饪用语
  sauté: 嫩煎
  arrow root: 葛粉
  mise en place: 备料

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

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

何时使用术语表

• 开源项目 — 确保品牌名称和技术用语在各语言翻译中保持一致。
• 文档网站 — 统一标准用语（例如：永远将 “container” 翻译为”容器”）。
• 法规行业 — 锁定法律或医学用语的翻译。
• 多人翻译流程 — 确保每个人使用相同的词汇。

小技巧

• 从小处开始。 发现不一致时再加入词汇。10–20 个词汇足以覆盖大多数项目。
• 品牌名称用 ~。 “GitHub”、“Kubernetes”、“Docker” 这类词汇几乎永远不该被翻译。
• 通用词汇放全局术语表。 将品牌名称和常见技术用语放在 ~/.config/yaku/glossary.yaml，让它们应用到所有项目。
• 项目术语表放在工作目录。 yaku 会在执行命令的目录中查找 .yaku-glossary.yaml。
• 搭配 --context 使用。 术语表处理特定词汇；--context 设置整体语气和领域。