Translation Glossary

The glossary system ensures consistent translation of technical terminology across all documents. When Claude encounters a glossary term, it uses the specified translation rather than choosing its own.

Built-in glossaries¶

These glossaries ship in the action repository (resolved from the checked-out repo at runtime — they are not baked into the bundle) and load automatically when the target-language matches. No configuration needed.

The French glossary began as a machine-drafted economics glossary; native-speaker review is incorporated incrementally — programming-domain terms were reviewed in #78 and extended from the first native-editor lecture reviews (lecture-python-programming.fr #24/#25, August 2026).

How it works¶

The glossary is included in every translation prompt sent to Claude. For example, when translating to zh-cn, Claude sees:

GLOSSARY:
  - "utility function" → "效用函数"
  - "Bellman equation" → "贝尔曼方程"
  - "steady state" → "稳态"
  ...

This applies to all translation modes: sync (UPDATE, NEW), forward RESYNC, and whole-file translation.

Glossary format¶

Each glossary is a JSON file with this structure:

{
  "version": "1.0",
  "description": "Technical terms for quantitative economics",
  "terms": [
    {
      "en": "utility function",
      "zh-cn": "效用函数",
      "context": "economics"
    },
    {
      "en": "Bellman equation",
      "zh-cn": "贝尔曼方程",
      "context": "dynamic programming"
    }
  ]
}

Each term has:

• en — The English term (matched in source content)

• {lang-code} — The target language translation (e.g., zh-cn, fa)

• context — Optional category for disambiguation (e.g., economics, statistics, programming)

Using a custom glossary¶

To use your own glossary instead of the built-in one, specify the glossary-path input:

- uses: QuantEcon/action-translation@v0
  with:
    mode: sync
    glossary-path: 'glossary/my-custom-glossary.json'
    # ... other inputs

glossary-path is an override, not an addition or a fallback: when set it is the only glossary used, and a file that cannot be read or parsed fails the run rather than silently reverting to the built-in terminology. Set it on every mode the repo runs — sync, rebase and review — so the translation is judged against the same terminology it was produced against. A review running on a different glossary from its sync will flag deliberate terminology choices as defects and miss violations of the terms the edition actually adopted, and since terminology is a gating category it will block auto-merge on correct work.

For the CLI, glossaries are loaded automatically based on the language code. The forward and init commands resolve candidates in this order, and report which one they used:

Every run prints the glossary it loaded (✓ Loaded built-in glossary for zh-cn — 357 terms (…)) or warns that it found none and lists every path it tried. A malformed glossary is an error rather than a silent skip.

Adding terms to a glossary¶

1. Edit the relevant glossary file (e.g., glossary/zh-cn.json)

2. Add new term objects to the terms array

3. Follow these quality guidelines:

   • Use established translations from authoritative sources

   • Include context when a term has multiple translations in different fields

   • Prefer commonly accepted academic translations

   • Keep terms concise — short phrases, not full sentences

Example — adding a new term:

{
  "en": "Pareto efficiency",
  "zh-cn": "帕累托效率",
  "context": "welfare economics"
}

Adding a new language¶

To add glossary support for a new language:

1. Create glossary/{lang-code}.json (e.g., glossary/ja.json)

2. Use the same JSON structure as existing glossaries

3. The target language field should match the language code (e.g., "ja" for Japanese)

4. The glossary is loaded automatically when target-language matches the file name

Planned languages: Japanese (ja), Spanish (es)

Context categories¶

Terms use these context categories for disambiguation: