Translations

How Polyglot translates your strings, manages caching, and produces output files.

Translate only the reviewed screen

Apply your saved plan first. --plan limits translation to that plan’s changed source keys. --estimate reports the local pending work and reuse without a network call; it is not an exact currency quote and cannot predict the hosted cache. Sign in when the hosted operation needs it, then repeat the same scoped command to resume.

polyglot translate --plan <plan-id> --languages fr --estimate
polyglot translate --plan <plan-id> --languages fr

How it works

1. polyglot scan detects untranslated strings in your source files.
2. polyglot translate sends those strings to the Polyglot API.
3. The API translates them using LLMs with context from your glossary, translation memory, and framework metadata.
4. Translation files are written to your configured output directory.

Incremental translation

Polyglot maintains a .polyglot-cache.json file that tracks SHA-256 content hashes for each source file. On subsequent runs, only files that have changed are re-scanned and only new or modified strings are sent for translation.

To force a full retranslation, use the --force flag:

polyglot translate --force

Translation memory

The Polyglot API maintains a per-project translation memory. If a string was previously translated (even in a different file), the existing translation is reused. This ensures consistency across your codebase and reduces API costs.

Sync existing translations from your repo

If you translated locally — before connecting the dashboard, or while the backend was behind — your repo holds translations the backend's memory doesn't. Run polyglot push once to upload them, so coverage reflects reality and the dashboard won't re-translate what you already have.

polyglot push

Push is additive and safe to re-run: it only adds pairs the backend is missing, never overwrites an existing translation, and generates no new translations. See the CLI reference for the full command.

Keep keys stable when copy or components change

Keep an existing key when moving a component. Add explicit meaning for ambiguous source text in translation.contexts. Two Open messages with different contexts have separate translation memory and approval identity. Changing the source or context invalidates the previous meaning’s approval; moving the source location alone does not.

[translation.contexts]
"file.open" = "Button that opens a document"
"store.open" = "Status indicating the shop is currently open"

Resume partial failures and preserve reviews

A failed or structurally invalid row stays pending while valid siblings and human approvals are retained. Fix the reported placeholder, ICU, tag or source-owned-code problem and rerun incremental translation. Do not use --force as the default retry strategy or delete the cache to clear an error.

Hosted workbench saves use revision preconditions. If another reviewer changed the translation, preserve your draft, load the latest revision, reconcile it and save again. Structural rejection preserves the draft and prior history. Translation generation, local editing and importing are not human approval.

Review, publish and recover the next change

Inspect changed copy and estimate pending work. Sync the current keyed source identity, review hosted translations, then pull only approvals matching that snapshot. Pending, rejected and stale-meaning translations are excluded. A source move keeps identity when the keys and meanings remain stable.

Approved pull records its local catalog writes with a run ID. Inspect its recovery diff before undoing it. Undoing a local pull does not reverse a remote PR merge; use your repository’s reviewed revert/resync workflow for that change. The managed catalog-sync CLI pin must adopt the context-capable release before that managed path can promise context-aware synchronization.

polyglot diff
polyglot translate --languages fr --estimate
polyglot translate --languages fr
polyglot catalogs sync
# Review and approve current translations in the dashboard.
polyglot pull --approved-only
polyglot runs
polyglot undo <approved-pull-run-id> --diff

Provider changes and translation integrity

Local planning, review and recovery do not depend on the translation provider. Hosted translation retries are bounded; configured provider identity failures are surfaced instead of silently accepting a different reported model. A provider change still needs structural and human language qualification. The CLI does not choose a provider from your app configuration.

Keep pending work and retry after the service or authentication issue is resolved. Structural checks and reported model identity do not by themselves prove semantic translation quality or future model availability.

Output formats

Translations can be output in multiple formats depending on your framework:

Set the format in polyglot.toml or override per-run:

polyglot translate --format yaml
polyglot export --format arb

Targeting specific languages

By default, all languages in your config are translated. To translate a subset:

polyglot translate --languages es,fr

Key styles

The key_style setting controls how translation keys are structured:

# nested (default) — dot paths become nested objects
{
  "app": {
    "page": {
      "title": "Bienvenido"
    }
  }
}

# flat — keys are dot-separated strings
{
  "app.page.title": "Bienvenido"
}

Coverage tracking

After translating, check how complete your translations are:

polyglot coverage

┌──────────┬─────────┬────────┬──────────┐
│ Language │ Strings │ Done   │ Coverage │
├──────────┼─────────┼────────┼──────────┤
│ es       │     42  │    42  │   100.0% │
│ fr       │     42  │    38  │    90.5% │
│ de       │     42  │    42  │   100.0% │
└──────────┴─────────┴────────┴──────────┘

Diff

See what strings have been added, modified, or removed since the last translation run:

polyglot diff

┌────────┬───────────────────────────┬──────────┐
│ Status │ String                    │ File     │
├────────┼───────────────────────────┼──────────┤
│ added  │ "New feature"             │ page.tsx │
│ changed│ "Updated heading"         │ page.tsx │
│ removed│ "Old button label"        │ nav.tsx  │
└────────┴───────────────────────────┴──────────┘

Validation

Check for common translation issues — missing interpolation variables, placeholder mismatches, and excessive length differences:

polyglot validate