buildtranslator.json

Full reference for the PolyCLI configuration file.

PolyCLI looks for buildtranslator.json in the current working directory when you run npx @polycli/cli run. Generate it with npx @polycli/cli init or create it manually.

Field reference

Field	Type	Required	Description
sourceLanguage	string	Yes	The BCP 47 language code of your source file (e.g. "en", "it"). The source JSON file is expected at <localesPath>/<sourceLanguage>.json.
targetLanguages	string[]	Yes	Array of BCP 47 language codes to translate into. One output file is created per language.
localesPath	string	Yes	Relative path to the folder containing your JSON locale files (e.g. "./locales").
markdownPath	string	No	Relative path to the folder containing Markdown files to translate. See the Markdown Translation guide for the expected folder structure.
arbPath	string	No	Relative path to the folder containing Flutter .arb localisation files. Source file expected at <arbPath>/<arbPrefix>_<sourceLanguage>.arb.
arbPrefix	string	No	Filename prefix for .arb files. Defaults to "app". Combined with the language code to form filenames like app_en.arb.
translateArbDescriptions	boolean	No	When true, the description field inside @key metadata blocks is also translated. Defaults to false. Descriptions are developer notes — enable only if they are user-facing.
tone	string	No	Translation register and style, max 200 characters. Applied to all target languages. Example: "Professional and technical, developer-focused."
glossary.doNotTranslate	string[]	No	Terms that are never translated. Replaced with opaque tokens before the AI sees the text — 100% guarantee.
glossary.preferredTranslations	object	No	Per-term translation guidance. Values can be a global instruction string or a per-language map of exact translations.

Full example

buildtranslator.json

{
  "sourceLanguage": "en",
  "targetLanguages": ["es", "fr", "de", "it", "ja"],
  "localesPath": "./locales",
  "markdownPath": "./docs",
  "arbPath": "./lib/l10n",
  "arbPrefix": "app",
  "translateArbDescriptions": false,
  "tone": "Professional and technical, developer-focused.",
  "glossary": {
    "doNotTranslate": ["PolyCLI", "Init", "Edit", "Run"],
    "preferredTranslations": {
      "Early Bird": "Use the local idiomatic term for an early-adopter discount",
      "pipeline": { "de": "Pipeline", "it": "pipeline" }
    }
  }
}

With markdownPath set, PolyCLI expects Markdown source files at ./docs/en/*.md and will write translations to ./docs/es/*.md, etc.

doNotTranslate vs preferredTranslations

doNotTranslate gives a 100% guarantee: terms are replaced with opaque tokens ([GLOS0], [GLOS1], …) before the AI ever sees the text, and restored verbatim afterward. Use this for brand names, CLI command names, and any term that must never change.

preferredTranslations injects guidance into the AI system prompt — a ~95% guarantee. Use this for terms that require grammatical adaptation in the target language (declension, gender agreement, idiomatic equivalents). Values can be a global instruction string or a per-language map of exact translations.