verbatra translate
Translate every target locale once, then exit.
Run one translation pass over every target locale, then exit. translate reads the source locale, diffs it against the lock file, sends only the new or changed strings to the provider, runs the integrity checks, writes the locale files, and updates the lock. Anything still current is never re-sent, so you never pay twice for an unchanged string.
Synopsis
verbatra translate [flags]Flags
| Flag | Argument | Default | Effect |
|---|---|---|---|
--cwd | <path> | current directory | resolve config and locale files from this directory |
--config | <path> | search for one | load this config file instead of searching for one |
--locales | <list> | every configured target locale | translate only this comma-separated subset; an unconfigured locale fails the run with UNKNOWN_LOCALE before anything is read or spent, and an empty list is a usage error, exit 2 |
--dry-run | none | off | preview changes without calling a provider or writing files (no API key needed) |
--prune | none | the config's prune option, otherwise off | remove orphaned keys (in a target file but absent from source) from the written file and the lock |
--lock-timeout | <seconds> | 600 | how long to wait for a held per-locale write lock before failing; must be a bare positive integer of seconds (a value like 60s, 0, or -1 is a usage error, exit 2) |
--concurrency | <n> | 1 | translate up to n target locales at once; must be a positive integer |
--no-cache | none | off (cache on) | bypass the local translation-memory cache (verbatra.cache.json) for this run |
--json | none | off | print one JSON envelope on stdout carrying the run summary under result (the RunSummary shape), or the error code on a failed run; the human-readable error line still goes to stderr |
By default a run deletes nothing: orphaned keys are reported and left in place. --prune removes exactly those keys and nothing else, and overrides the config's prune option for this run. Before it runs, translate loads .env.local and then .env from the working directory; a variable already set in the real environment wins.
--dry-run constructs no provider at all, so it needs no API key and cannot spend anything: it reads the source and target files, diffs them against the lock file, and reports exactly what a real run would change. It writes nothing (no locale file, no lock update, no run-status snapshot), it neither reads nor writes the cache, and it takes no per-locale write lock, so it never waits on a run already in progress. The .env load above still happens on a dry run; there is simply no key to read. That makes it a complete way to try verbatra on a real project before creating a provider account.
--locales de,fr narrows the run to a subset of the configured targets. Locales left out are untouched: their files, their lock entries, and their cache entries all stay as they were. It is the flag to reach for on a rate-limited free tier, where translating one locale at a time is the only way through, and it is also the fastest way to re-run a single locale that came out partial. The run-status snapshot always describes the most recent run alone, so a subset run narrows it to that subset.
--lock-timeout tunes how long a locale waits for a contended write lock before the run fails with LOCK_CONTENDED: raise it when another run legitimately holds the lock for a while, lower it to fail fast in CI.
--concurrency runs several target locales in parallel to finish a large project faster. It is refused with exit 2 when the config sets a maxTokens budget, because concurrent locales cannot honor a token cap deterministically (a dry run is exempt). If a whole-run error (in practice a corrupt lock file) surfaces once locales are already running, no further locale is started, and the ones in flight finish and release their write locks before the command exits with 2, so the run leaves no lock behind for the next one to wait on. As a run advances, progress is printed to stderr (one line per locale start, provider sub-batch, and locale finish), so a --json run's stdout stays a single clean summary. --no-cache skips the translation-memory cache for the run, making exactly the provider calls it would with no cache present.
Examples
# translate once using the config it finds
verbatra translate
# preview the keys that would be pruned, spending nothing
verbatra translate --prune --dry-run
# one locale at a time, which is what a rate-limited free tier needs
verbatra translate --locales deExit codes
| Code | Meaning |
|---|---|
0 | every target locale came out complete |
1 | the run finished but one or more locales failed or came out partial |
2 | could not run: a whole-run error (config, source, format, provider, or lock), or a usage error |
One locale failing is not fatal: the run finishes, exits 1, and the per-locale detail sits in the summary. A partial locale exits 1 as well. That is a locale whose file was written but still has keys missing, typically because a provider sub-batch failed or the integrity gate refused a translation, and shipping it as a success would leave a half-translated file in your repository unnoticed.
Related
- How it works explains the read, diff, translate, write pipeline.
- The cache explains what
--no-cachebypasses and how reuse is scoped. - Translation safety covers the integrity checks and the needs-review queue.
verbatra diffpreviews the same pending keys read-only.- CI and exit codes shows how to branch on these codes.