verbatra watch

Watch the source locale file and re-run a translation on each debounced change, until you interrupt it. watch runs an initial translation at startup, then keeps your target locales current as you save. Before it runs, it loads .env.local and then .env from the working directory; a variable already set in the real environment wins.

Synopsis

verbatra watch [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	watch and translate only this comma-separated subset; an unconfigured locale is rejected at startup with `UNKNOWN_LOCALE` before any watching begins, and an empty list is a usage error, exit `2`
`--debounce`	`<ms>`	`300`	wait this many milliseconds after the last change before translating; must be a bare positive integer (a value like `250ms`, `0`, or `-1` is a usage error, exit `2`)
`--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 per run; must be a positive integer
`--no-cache`	none	off (cache on)	bypass the local translation-memory cache (`verbatra.cache.json`) on every run
`--json`	none	off	print each run as one JSON envelope on stdout, NDJSON style (one object per line)

With --json, each run emits one envelope record with command: "watch": an ok: true record carrying that run's RunSummary under result, or an ok: false record carrying an error code and message. The startup line, the stopping notice, and per-run progress all go to stderr, so the stdout stream stays clean NDJSON. A failed run is just a record on the stream: it neither stops the watcher nor changes the exit code.

--locales de,fr narrows every cycle of the session to a subset of the configured targets, which keeps a development loop cheap when you only care about one language. The subset is validated once at startup rather than on each run.

--lock-timeout applies to every cycle: it tunes how long a locale waits for a contended write lock before that run fails with LOCK_CONTENDED. A failed run is only a record on the stream, so the watcher keeps going either way.

--concurrency applies to each cycle's run. Because each run's token budget is fresh, a --concurrency above 1 cannot be honored when the config sets a maxTokens budget: watch refuses that combination at startup and exits 2 before the initial run, instead of starting a session that fails every cycle. --no-cache bypasses the translation-memory cache on every cycle.

Stopping

The first interrupt (Ctrl-C, or SIGTERM) lets the current run finish, stops the watcher cleanly, and exits 0. A second interrupt while that shutdown is still in flight force-stops with exit 130.

Examples

# watch and re-translate on each change
verbatra watch

# calmer in a busy editor: wait 1s after the last change, stream NDJSON
verbatra watch --debounce 1000 --json

# keep only German current while you work
verbatra watch --locales de

Exit codes

Code	Meaning
`0`	stopped cleanly by a single interrupt
`2`	could not start or stop: a config error, a startup or shutdown failure, or a usage error (including an invalid `--debounce`)
`130`	force-stopped by a second interrupt

verbatra translate is the one-shot run watch repeats.
The cache explains what --no-cache bypasses on each run.
How it works explains what each run does.
The SDK reference documents the WatchRunResult and RunSummary shapes.

Edit on GitHub