Skip to content

Glossary ​

The glossary ensures consistent product terminology across translations. Users can define a term's translation in one or multiple languages, allowing the AI model to use this predefined translation instead of choosing one itself. It can also be used to keep certain terms, such as product names, unchanged during translation into other languages.

Two kinds of guidance are sent to the model:

  • Term rows in glossary.userGlossary (and, for documentation, JSON, and SVG, existing UI translations from each ui block with uiGlossary left on). A row is included only when that source term appears in the text being translated.
  • Project context files in glossary.contextFiles. The full brief is injected into every UI, docs, JSON, SVG, and proofread prompt. That section is below.

How the glossary works ​

Where terms come from ​

SourceConfigUsed by
UI catalogsui[].uiGlossary (boolean, default true) — that block's stringsJsontranslate-docs, translate-json, translate-svg
User CSVglossary.userGlossarytranslate-ui, proofread-ui, translate-docs, translate-json, translate-svg

init points glossary.userGlossary at glossary-user.csv and does not create that file. Run glossary-generate when it is missing, and put domain terms in it before the first translate-ui. A second translation of an unchanged string can come back worded differently. The glossary is what makes the two runs agree.

A block with uiGlossary: true reuses translations already stored in its strings.json as hints, so documentation, JSON, and SVG stay aligned with the UI. translate-ui and proofread-ui do not read those catalogs — they only take hints from the user CSV, so a bad UI translation is not fed back in as the preferred term. Set uiGlossary to false on a block that should not steer other pipelines. When several blocks share a source term, the earlier block fills a locale and later blocks add only locales that are still missing. The user CSV wins over every UI catalog. A row whose locale is a specific code replaces both the * row and the UI-catalog translation for that locale. A locale of * applies the same translation to every target locale that does not already have one from a UI catalog.

Compact UI-label abbreviations (a trailing dot such as Alm., or a short single-token compression such as Size → Tam) stay available for UI translation. Document prompts skip them, so they do not push models toward invented {{…}} tokens in markdown or MDX.

A multi-word prefix shared by two or more catalog keys is added as its own term when that prefix is not already a key. For each locale, the translation is the shared start of those catalog translations, cut on a word boundary, and only when that shared start is at least four characters. Cursor Models run out and Cursor Models at renewal can yield Cursor Models when both German strings start with Cursor-Modelle. A user CSV row for the same source replaces that seeded translation.

When a term is sent ​

Matching is case-insensitive and stops at a word boundary (whitespace or punctuation). Longer terms are preferred, and overlapping matches are dropped. When a term matches the current batch, the prompt receives a hint like "dashboard" → "Tableau". If that row has a Context note, the note is appended for that match only.

Context is source-language usage guidance (what the term means, or how to use it). It is not a translation. Changing a Context note, or any glossary.contextFiles content, refreshes cached translations for the affected locale on the next run — you do not need --force. Changing only the preferred Translation on a row that is not Force keeps the existing cache until you pass --force or --force-update. A Force row (new, edited, or cleared) misses the cache only for segments whose source contains that term, and only when the stored text does not already include the forced translation. Leave Context empty on that row for this narrow refresh; a Context note still refreshes the whole locale. Rows you edited in the dashboard stay as user-edited.

Markdown translation checks a UI label of two to five words when the source cites it as the whole bold or inline-code span, in a heading, or on a line that is only that label. A longer bold phrase that contains the term is a hint, so **Ask for target language** does not require the catalog form of Target language. Single-word hints may still be inflected. A user-CSV hint that is not also a UI label stays a hint. The check ignores capitalization and looks for the catalog wording as a substring, so an inflected form can still miss. It tries the next model until that same quality error has occurred three times or the model list runs out, and it does not split the segment for a label miss. If those attempts miss only that check, the run keeps the attempt with the fewest misses, writes the document, and caches the segment with a glossary-label warning. The summary lists those warnings, and cacheDir receives glossary-review-*.md, a prompt you can paste to an AI to mark each miss as a false positive or a real miss. The exit code stays 0 when the only problem is that warning.

A false positive can be skipped with glossary.labelCheckSkips in the project config (the dashboard Glossary tab edits the same list). Each entry names the English term, the locales to skip (* means every locale), and optional files globs. The term remains a prompt hint. --recheck-glossary-warnings translates flagged segments again and clears the flag when the check now passes. --force re-translates them with every other segment. Cached markdown is rechecked when the file is processed (--force-update); a file that file tracking skips is left as it is until a Force term in that file is missing from the output, or until --recheck-glossary-warnings opens a file that has a flagged segment. A catalog translation that differs from the source is required wherever that label is cited, including a translated product name. Keep the source spelling with a Force row whose translation equals the source.

Force ​

When Force is true, yes, or 1, the source term is taken out of the text before the model sees it and the preferred translation is written back afterward. The wording is exact, not a suggestion. The same word-boundary and longest-match rules apply. Leave Force empty (or false) when the model should prefer the translation but may still inflect it.

Generate a glossary ​

glossary-generate writes an empty CSV with the standard header. It uses glossary.userGlossary from config, or glossary-user.csv when that key is unset. It refuses to overwrite a file that already exists (exit 1).

bash
ai-i18n-tools glossary-generate
# or: ai-i18n-tools glossary-generate -o i18n/glossary.csv

Point config at the file:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv"
  }
}

You can also create the CSV glossary file directly from the dashboard. The first Add action on the Glossary tab will create the file if glossary.userGlossary is specified and the file does not already exist. When glossary.autoAddUserEditedToGlossary is true (the default), correcting a UI string in the dashboard can add that change to the CSV during the next translate-ui run. The dashboard also serves as an editor for the CSV glossary, allowing you to add, edit, or filter rows within the UI.

CSV columns ​

Header row:

text
Original language string,locale,Translation,Force,Context

en or English is accepted instead of Original language string. Notes is accepted instead of Context.

ColumnMeaning
Original language stringSource term or phrase, in the source locale
localeTarget locale code, or * for every target
TranslationPreferred translation
Forcetrue, yes, or 1 to require this wording; otherwise a hint
ContextOptional source-language explanation. Sent only when this term matches

Examples ​

One product term for every locale, a forced German label, and a French row that explains a word the model might take literally:

csv
"Original language string","locale","Translation","Force","Context"
"dashboard","*","Tableau","false","The analytics home, not a vehicle panel"
"Save","de","Speichern","true",""
"workspace","fr","espace de travail","false","A user's project container, not an office"

Combined with a project brief:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"],
    "contextMaxChars": 12000
  }
}

Field reference: glossary in Configuration. Command reference: glossary-generate.

Project context files ​

glossary.contextFiles is for product-level guidance that does not belong in a single CSV row: what the product is, who it is for, tone, and terms that are easy to mistranslate. Point config at one or more cwd-relative .md / .txt files; they are concatenated in listed order and injected into every UI, docs, JSON, SVG, and proofread prompt.

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"]
  }
}

Write the brief in the source locale, keep it well under glossary.contextMaxChars (default 12000), and store it outside docs[].contentPaths unless you also want that file translated. See glossary in Configuration.

Generate a context file with an AI agent ​

Ask an agent (Cursor, Claude Code, Copilot, and similar) to read the repo and write the brief. Paste a prompt like this:

text
Create a translation-context Markdown file for this repository at i18n/product-context.md.

This file is injected verbatim into every ai-i18n-tools translation prompt (UI strings, docs, JSON, SVG, proofread). It must stay in the source language of the project (do not translate it). Translators already receive a glossary of preferred term mappings; this file should explain meaning, audience, and register — not duplicate every glossary row.

Requirements:
- Concise: aim for 1–4 KB, hard limit 8000 characters. No full manuals, README dumps, or changelog history.
- Source-language only. Short headings, bullet lists, and a few example sentences are enough.
- No secrets, API keys, credentials, personal data, internal URLs, or unpublished commercial figures.
- Do not invent product facts. If something is unclear, omit it or mark it as unknown.
- Do not put this file under a path that is also listed in docs[].contentPaths.

Cover, in this order:
1. Product in one paragraph: what it is, who uses it, and the default tone (formal / informal / technical).
2. Domain and disambiguation: terms that look ordinary in English but have a product-specific meaning (for example “dashboard” as an analytics home, not a vehicle panel).
3. Features or areas that change register (billing vs. onboarding vs. admin).
4. Things translators must preserve exactly: brand names, CLI flags, config keys, code identifiers, placeholder tokens.
5. Locale notes only when they affect meaning for every target (for example “use formal you”). Do not list per-locale translations here.

Write only the Markdown file. Afterward, remind me to add it to glossary.contextFiles in ai-i18n-tools.config.json if it is not already listed.

Review the file before the next sync / translate-* run. Changing the file invalidates cached translations for each locale on that run, so keep the brief stable once quality is good.

Released under the MIT License.