Introduction
PolyCLI automates i18n translation for your frontend JSON files and Markdown docs using the provider.
What is PolyCLI?
PolyCLI is a command-line tool that translates your app's localisation files automatically. It integrates with your build pipeline, uses the provider to produce high-quality translations, and tracks exactly which strings have changed — so you never pay to re-translate content that hasn't moved.
How it works
Initialise
Run npx @polycli/cli init once in your project root. PolyCLI writes a buildtranslator.json config file with your source language, target languages, and folder paths.
Edit your source file
Add or modify strings in your source-language JSON file (e.g. locales/en.json). PolyCLI uses a local lockfile to remember what was last translated.
Run the translation
Run npx @polycli/cli run --key YOUR_KEY. Only new or modified strings are sent to provider. Translated files are written to disk. Your credit balance is decremented only for what was actually translated.
Key features
Delta algorithm
Only translates new or modified strings. Unchanged content is never re-sent to the API.
Variable preservation
{{name}}, ICU plurals, HTML tags, and custom tokens are tokenised before translation and restored after.
JSON + Markdown
Handles both i18n JSON files and Markdown documentation with separate delta tracking per file type.
Structured Outputs
Uses Structured Outputs (strict JSON schema) — keys are never added, removed, or renamed.
Credit-based billing
Buy credits once, use them as you translate. Credits are counted after variable extraction, never expire.
CI-friendly
Runs as a plain Node.js binary. No daemon, no watch mode. Run it in your build step or on a schedule.