Glossary

Protect brand names and CLI commands from translation, and guide the AI toward preferred terminology.

The glossary config has two independent mechanisms with different guarantee levels. Both live under the glossary key in buildtranslator.json.

doNotTranslate — 100% guarantee

Terms listed here are replaced with opaque tokens ([GLOS0], [GLOS1], …) before the text is ever sent to the AI. The AI never sees the original term, so it cannot translate, reformat, or alter it in any way. Tokens are restored verbatim after translation.

Use this for brand names, product names, CLI command names, and any term that must remain byte-for-byte identical in every output language.

buildtranslator.json

{
  "glossary": {
    "doNotTranslate": ["PolyCLI", "Init", "Edit", "Run"]
  }
}

Matching is whole-word and case-sensitive. The longest term is matched first, so overlapping entries never conflict.

preferredTranslations — ~95% guarantee

Terms listed here are injected as instructions into the AI system prompt. The AI sees the original text and is told how to translate specific terms — but it retains awareness of grammar, declension, and gender agreement in the target language.

Use this for terms that require grammatical adaptation: words that need a different form depending on case, gender, or idiomatic usage in the target language.

The value can be a global instruction string or a per-language map of exact translations.

buildtranslator.json

{
  "glossary": {
    "preferredTranslations": {
      "Early Bird": "Use the local idiomatic term for an early-adopter discount",
      "pipeline": { "de": "Pipeline", "it": "pipeline", "fr": "pipeline" }
    }
  }
}

Using both together

buildtranslator.json

{
  "sourceLanguage": "en",
  "targetLanguages": ["es", "fr", "de", "it", "ja"],
  "localesPath": "./locales",
  "glossary": {
    "doNotTranslate": ["PolyCLI", "Init", "Edit", "Run"],
    "preferredTranslations": {
      "Early Bird": "Use the local idiomatic term for an early-adopter discount",
      "pipeline": { "de": "Pipeline", "it": "pipeline" }
    }
  }
}

doNotTranslate terms are also stripped before word counting — you are never charged for protected terms.

Glossary in Markdown files

Both glossary mechanisms apply equally to Markdown translation. Terms in doNotTranslate are tokenized in Markdown content before translation and restored verbatim afterward — exactly as they are for JSON files. Brand names and CLI commands will never be altered in translated Markdown output.