translate

The translate command is the core of translate-kit. It reads your source locale JSON, computes a diff against existing translations, and sends only new or modified keys to the AI for translation.

Usage

translate-kit translate

Flags

Flag	Description
`--dry-run`	Preview changes without writing files
`--force`	Ignore lock file, re-translate everything
`--locale <code>`	Translate only a specific locale
`--verbose`	Show detailed output

Examples

# Translate all target locales
translate-kit translate

# Only translate Spanish
translate-kit translate --locale es

# Preview what would be translated
translate-kit translate --dry-run

# Force re-translate everything
translate-kit translate --force

How It Works

Keys mode (default)

For each target locale:

Load the source locale JSON (e.g. messages/en.json)
Load the existing target JSON and lock file
Flatten nested keys for comparison
Compute diff — added, modified, removed, and unchanged keys
Send added/modified keys to the AI model in batches
Merge translations back into the target JSON (nested structure)
Update the lock file with current source hashes

Inline mode

The same pipeline applies, but with two differences:

Source: reads .translate-map.json (inverted: key → text) instead of en.json
Output: target JSON files are flat ({"hero.welcome": "..."}) since the <T> component does flat key lookup

The lock file (.translate-lock.json) stores SHA-256 hashes of source values. If a source value changes, its key is marked as modified and re-translated.

Keys are sent to the AI in batches controlled by translation.batchSize (default: 50). Multiple batches run in parallel up to translation.concurrency (default: 3). Failed batches are retried up to translation.retries times (default: 2).