--- title: "verbatra watch" description: "Übersetze bei jeder Quelländerung neu, bis du abbrichst, damit die Locale-Dateien synchron bleiben; jeder Lauf schickt nur neue und geänderte Keys." type: "reference" --- # verbatra watch Übersetze bei jeder Quelländerung neu, bis du abbrichst, damit die Locale-Dateien synchron bleiben; jeder Lauf schickt nur neue und geänderte Keys. Beobachte die Quell-Locale-Datei und führe nach jeder entprellten Änderung eine neue Übersetzung aus, bis du unterbrichst. `watch` startet mit einer initialen Übersetzung und hält deine Ziel-Locales dann aktuell, während du speicherst. Jeder Lauf arbeitet wie [`verbatra translate`](https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md), nur dass `watch` kein `--dry-run`, `--prune`, `--include-human`, `--estimate` oder `--max-tokens` hat und nie mit `3` endet. Beim Start ergänzt es außerdem fehlende Einträge in einer vorhandenen `.gitignore`, siehe [.gitignore-Einträge](https://verbatra.kreitz-webdev.de/de/docs/cli.md#gitignore-einträge). ## Synopsis [#synopsis] ```bash verbatra watch [flags] ``` ## Beispiele [#beispiele] ```bash # beobachten und bei jeder Änderung neu übersetzen verbatra watch # ruhiger in einem hektischen Editor: 1 s nach der letzten Änderung warten, NDJSON ausgeben verbatra watch --debounce 1000 --json # nur Deutsch aktuell halten, während du arbeitest verbatra watch --locales de ``` ## Flags [#flags] | Flag | Argument | Standard | Wirkung | | --- | --- | --- | --- | | `--locales` | `` | jede konfigurierte Ziel-Locale | nur diese kommagetrennte Teilmenge beobachten; einmal beim Start geprüft, wo eine nicht konfigurierte Locale mit `UNKNOWN_LOCALE` scheitert | | `--debounce` | `` | `300` | so viele Millisekunden nach der letzten Änderung warten, bevor übersetzt wird; eine Ganzzahl von `1` bis `60000` | | `--lock-timeout` | `` | `600` | in jedem Lauf so lange auf eine gehaltene Schreibsperre einer Locale warten; eine Ganzzahl von `1` bis `3600` | | `--concurrency` | `` | `1` | pro Lauf bis zu `n` Ziel-Locales gleichzeitig übersetzen; eine Ganzzahl von `1` bis `100`, abgelehnt bei einem `maxTokens`-Budget | | `--no-cache` | keins | aus (Cache an) | den [Übersetzungsspeicher-Cache](https://verbatra.kreitz-webdev.de/de/docs/the-cache.md) (`verbatra.cache.json`) bei jedem Lauf umgehen | Nimmt außerdem die [globalen Flags](https://verbatra.kreitz-webdev.de/de/docs/cli.md#globale-flags) `--cwd`, `--config` und `--json`; hier gibt `--json` einen Datensatz pro Lauf aus. Vor dem Start lädt `watch` die [Umgebungsdateien](https://verbatra.kreitz-webdev.de/de/docs/cli.md#umgebungsdateien). ## Verhalten [#verhalten] ### Jeder Lauf [#jeder-lauf] Jeder Lauf übersetzt die `--locales`-Teilmenge oder jedes Ziel, mit einem frischen Token-Budget. Eine Locale, deren [Schreibsperre](https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md) länger als `--lock-timeout` belegt bleibt, scheitert in der Zusammenfassung dieses Laufs mit `LOCK_CONTENDED`, während die übrigen Locales weiterlaufen; eine Sperre eines nicht mehr laufenden verbatra-Prozesses wird sofort übernommen. Ein fehlgeschlagener Lauf stoppt den Watcher nie. Das Warten auf eine Sperre gibt dieselbe Wartezeile aus, die unter [`translate`](https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md#schreibsperren-und-unterbrechungen) beschrieben ist. Eine `--concurrency` über `1` zusammen mit einem konfigurierten `maxTokens`-Budget wird beim Start mit Exit `2` abgelehnt, noch vor dem ersten Lauf, weil sonst die Reihenfolge der Locales entscheiden würde, welche ihre restliche Arbeit verliert. Ein Provider, der sich nicht erzeugen lässt, meist weil seine API-Key-Variable fehlt, wird ebenfalls beim Start abgelehnt: `watch` endet mit Exit `2` und `PROVIDER_CONSTRUCTION_FAILED` sowie einer `next:`-Zeile, die die Variable nennt, genau wie `translate`, statt auf Änderungen zu warten, die kein Lauf übersetzen könnte. Vor 0.12.0 wartete es weiter. ### Stoppen [#stoppen] Die erste Unterbrechung (Strg-C oder SIGTERM) lässt den aktuellen Lauf fertig werden, stoppt den Watcher und endet mit `0`. Eine zweite Unterbrechung, während das Herunterfahren noch läuft, erzwingt den Stopp mit Exit `130`, nachdem die Schreibsperren der Sitzung freigegeben wurden. Ohne `--json` schreibt stderr nach jedem Lauf `verbatra: waiting for changes...`, in einem interaktiven Terminal nach der Startzeile `verbatra: press Ctrl-C to stop` und nach dem Herunterfahren `verbatra: stopped`. `--quiet` lässt diese Zeilen weg, nicht aber die Startzeile und `verbatra: stopping, finishing current run...` bei der ersten Unterbrechung: Sie werden in jedem Modus geschrieben, `--json` eingeschlossen. ### JSON-Ausgabe [#json-ausgabe] Schema: [`watch-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/watch-envelope.json) validiert den ganzen Envelope; [Schemas](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#schemas) listet die übrigen auf. Mit `--json` ist stdout NDJSON: ein [Envelope](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#json-ausgabe) pro Lauf, mit `command: "watch"`. Ein erfolgreicher Lauf ist ein `ok: true`-Datensatz mit der [`RunSummary`](https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md#json-ausgabe) dieses Laufs; ein fehlgeschlagener Lauf ist ein `ok: false`-Datensatz mit dem eigenen Code des Fehlers, oder `WATCH_RUN_FAILED`, wenn er keinen hatte, plus seinem `hint`, falls vorhanden. Ein fehlgeschlagener Lauf ist nur ein Datensatz: Er stoppt den Watcher nicht und ändert den Exit-Code nicht. Startzeile, Stopp-Hinweis und Fortschritt gehen auf stderr. Ohne `--json` geht die Zusammenfassung eines Laufs auf stdout und die Zeile `verbatra: error [CODE] message` eines fehlgeschlagenen Laufs auf stderr. ### Rückmeldung im Terminal [#rückmeldung-im-terminal] Ohne `--json` nennt `watch` die Quelldatei, sobald sich eine Änderung daran gesetzt hat, und meldet den Lauf dann wie `translate`, mit demselben Spinner in einem interaktiven Terminal: ```text output verbatra: change detected: locales/en.json verbatra: translating de verbatra: de batch 1/1 verbatra: de: writing verbatra: de done, 1 translated verbatra: run finished, 1 locale processed verbatra: waiting for changes... ``` Diese Zeilen gehen auf stderr, und `--quiet` lässt sie weg. Siehe [Terminalausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#terminalausgabe). ## Exit-Codes [#exit-codes] | Code | Bedeutung | | --- | --- | | `0` | durch eine einzelne Unterbrechung sauber gestoppt | | `2` | konnte nicht starten oder stoppen: ein Konfigurationsfehler, ein Fehler beim Start oder Herunterfahren oder ein Verwendungsfehler wie ein ungültiges `--debounce` | | `130` | durch eine zweite Unterbrechung zwangsweise gestoppt | Ein fehlgeschlagener Lauf während der Sitzung ändert den Exit-Code nie. Siehe [den Exit-Code-Vertrag](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#exit-codes). ## Siehe auch [#siehe-auch] - [`verbatra translate`](https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md) ist der einmalige Lauf, den `watch` wiederholt. - [Der Cache](https://verbatra.kreitz-webdev.de/de/docs/the-cache.md) erklärt, was `--no-cache` bei jedem Lauf umgeht. - [So funktioniert es](https://verbatra.kreitz-webdev.de/de/docs/how-it-works.md) erklärt, was jeder Lauf tut. - [Menschliche Übersetzungen schützen](https://verbatra.kreitz-webdev.de/de/docs/protecting-human-translations.md) erklärt, warum ein Lauf einen veralteten Wert behält, den ein Mensch geschrieben hat. - [Die SDK-Referenz](https://verbatra.kreitz-webdev.de/de/docs/sdk.md) dokumentiert die Formen `WatchRunResult` und `RunSummary`.