JSON Translation

How PolyCLI reads, processes, and translates your i18n JSON files.

Source file

PolyCLI reads <localesPath>/<sourceLanguage>.json. The file can be flat or deeply nested — both structures are supported. Keys are never translated; only string values are sent to the translation API.

Variable preservation

Before sending strings to provider, PolyCLI replaces recognised interpolation tokens with opaque placeholders ([VAR0], [VAR1], ...). They are restored after translation. The model never sees the actual variable syntax, so it cannot accidentally translate or reformat it.

Pattern	Example	Used by
{{…}}	{{userName}}	Handlebars, Vue 3, react-i18next
{…} (single curly, 1-level nesting)	{count, plural, one {item} other {items}}	ICU MessageFormat, next-intl
<…> (HTML/JSX tag)	<strong>, </em>, <Trans>	React Trans component, HTML in strings
%%…%%	%%variable%%	Legacy PHP / custom systems

Before and after

locales/en.json (source)

{
  "greeting": "Welcome back, {{name}}!",
  "items": "You have {count, plural, one {# item} other {# items}} in your cart.",
  "nav": {
    "home": "Home",
    "settings": "Settings"
  }
}

locales/it.json (output)

{
  "greeting": "Bentornato, {{name}}!",
  "items": "Hai {count, plural, one {# articolo} other {# articoli}} nel carrello.",
  "nav": {
    "home": "Home",
    "settings": "Impostazioni"
  }
}

Note that {{name}} and the ICU plural syntax are preserved exactly. The key structure (nav.home, nav.settings) is also unchanged.

Large file chunking

If your delta exceeds 1,500 translatable words, PolyCLI automatically splits it into chunks, translates each chunk independently, and merges the results. Top-level keys are never split across chunks — a nested object always stays together. Credit usage is identical to a single request: chunking does not add any overhead.

PolyCLI uses Structured Outputs with a dynamically generated JSON Schema derived from the delta object. This means the provider is contractually required to return exactly the same key structure — it cannot add, omit, or rename any key.