langsync translate

langsync translate fills empty (or missing) values in every non-reference locale by translating the reference value with an AI provider. Existing translations are never overwritten; the target always wins.

With namespaces configured, translation runs independently per namespace file.

Usage

langsync translate [--provider <provider>] [--model <model>] [--max-keys <n>] [--dry-run]

Flags

Flag	Default	Description
`--provider <name>`	config / `openai`	Override the configured AI provider.
`--model <model>`	config / default	Override the configured provider model.
`--max-keys <n>`	unlimited	Cap how many empty values a run translates.
`--dry-run`	`false`	Report what would be translated, no writes.

Providers

Provider	Status	API key env var
`openai`	Released	`OPENAI_API_KEY`
`deepl`	Released	`DEEPL_API_KEY`
`anthropic`	Experimental (flag)	`ANTHROPIC_API_KEY`
`gemini`	Experimental (flag)	`GEMINI_API_KEY`

Experimental providers are implemented and tested but gated behind LANGSYNC_AI_EXPERIMENTAL=1 until each graduates to released.

Configuration

export default defineConfig({
  // ...
  ai: {
    provider: 'openai',
    model: 'gpt-5-mini',
    // apiKey: process.env.OPENAI_API_KEY (read automatically when omitted)
  },
});

Behavior

Only keys empty or missing in a target and non-empty in the reference are sent to the provider.
Each translation request preserves placeholders and ICU syntax.
On any provider or transport error the command exits with code 1.
The reference locale file is never modified.
Missing namespace files in target locales are synthesized as empty trees and created only when translations are written.
Extra target-only namespace files are left untouched.
If no namespace files are discovered while namespaces is configured, the command fails with an actionable error.
Namespaced files are translated independently, so written output paths reflect your namespace layout (for example src/i18n/de/common.json).