Glossary

A glossary file enforces consistent terminology across translations. Define how specific terms should be translated — or kept untranslated — and yaku injects these rules into the LLM prompt.

Quick start

Create a file called .yaku-glossary.yaml in your working directory:

.yaku-glossary.yaml

en:
  déploiement: deployment    # always translate to this
  conteneur: container
  Kubernetes: ~              # keep as-is
  Docker: ~                  # keep as-is

Now translate as usual. yaku auto-loads the glossary:

yaku --to en -f docs.fr.md

The LLM receives instructions like:

• “Use these specific translations: déploiement → deployment, conteneur → container”
• “Keep these terms in their original language (do NOT translate them): Kubernetes, Docker”

File format

Glossary files use YAML. Terms are grouped by target language code:

<target-language>:
  <term>: <translation>     # translate to this value
  <term>: ~                 # keep in original language (YAML null)

You can include sections for multiple languages in one file:

en:
  conteneur: container
  Kubernetes: ~

es:
  container: contenedor
  Kubernetes: ~

yaku only loads the section matching your --to target language (case-insensitive match). For example, --to en matches en:, EN:, or En:. If no section matches, yaku uses an empty glossary.

Translation entries

Provide a string value to define how a term should be translated:

en:
  logiciel: software
  base de données: database
  apprentissage automatique: machine learning

When yaku translates to en, it injects these terms into the LLM prompt as required translations.

Keep-original entries

Use ~ (YAML null) to tell yaku to keep a term in its original language:

en:
  Kubernetes: ~
  Docker: ~
  API: ~
  GitHub: ~

This is useful for brand names, proper nouns, and technical terms that should not be changed during translation.

File lookup

When you use --glossary <path>, yaku loads only that file. Otherwise, yaku checks both default locations and merges them (terms from later files override earlier ones):

1. ~/.config/yaku/glossary.yaml — global terms shared across all projects (loaded first)
2. .yaku-glossary.yaml in the current working directory — per-project terms (loaded last, takes priority)

Both files are loaded if they exist. When the same term appears in both, the per-project file takes priority.

To skip glossary loading entirely:

yaku --to en --no-glossary -f docs.fr.md

Example: per-project + global glossary

Set up a global glossary for brand names you never want changed:

~/.config/yaku/glossary.yaml

en:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

es:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

Then add project-specific terms in each project:

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

en:
  conteneur: container
  déploiement: deployment
  service: service

When you run yaku --to en from /path/to/my-project/, both files are loaded. The global glossary keeps brand names unchanged; the project glossary enforces domain terms.

Explicit glossary path

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

When --glossary is used, only that file is loaded — the default paths are skipped.

How it works

1. Load — yaku reads the glossary file(s) and looks up the --to language section.
2. Inject — Translation entries become "Use these specific translations: logiciel → software". Keep-original entries become "Keep these terms in their original language: Kubernetes, Docker".
3. Translate — The LLM sees the glossary instructions alongside the text.
4. Verify — After translation, yaku runs a safety check (EnforceKeepOriginal) to verify that terms marked with ~ are still present in the output. This is a safety net — the primary enforcement happens via the prompt.

The prompt injection approach means the glossary works with all backends (Gemini, OpenAI, Anthropic, hosted) and all formats (text, Markdown, JSON, YAML).

Full example: translating a cooking blog

.yaku-glossary.yaml

en:
  # Keep dish names in their original language
  ratatouille: ~
  croissant: ~
  miso: ~
  dashi: ~

  # Standardize cooking terms
  sauté: sauté
  julienne: julienne
  mise en place: mise en place

es:
  ratatouille: ~
  croissant: ~
  sauté: saltear
  julienne: cortar en juliana

yaku --to en -f recipe.fr.md -o recipe.en.md

When to use a glossary

• Open-source projects — keep brand names and technical terms consistent across translations.
• Documentation sites — enforce standard terminology (e.g., always use “container” for “conteneur”).
• Regulated industries — lock down translations of legal or medical terms.
• Multi-translator workflows — ensure everyone uses the same vocabulary.

Tips

• Start small. Add terms only as you notice inconsistencies. A glossary with 10–20 terms covers most projects.
• Use ~ for brand names. Terms like “GitHub”, “Kubernetes”, and “Docker” should almost always stay unchanged.
• Use the global glossary for universal terms. Put brand names and common technical terms in ~/.config/yaku/glossary.yaml so they apply everywhere.
• Place per-project glossary in the working directory. yaku looks for .yaku-glossary.yaml in the directory where you run the command.
• Combine with --context. The glossary handles specific terms; --context sets the overall tone and domain.