--- title: "verbatra watch" description: "Retraduit à chaque changement de la source jusqu'à interruption pour garder les locales à jour ; chaque exécution n'envoie que les clés nouvelles ou modifiées." type: "reference" --- # verbatra watch Retraduit à chaque changement de la source jusqu'à interruption pour garder les locales à jour ; chaque exécution n'envoie que les clés nouvelles ou modifiées. Surveille le fichier de la locale source et relance une traduction après chaque changement temporisé, jusqu'à ce que tu l'interrompes. `watch` lance une traduction initiale au démarrage, puis garde tes locales cibles à jour au fil de tes sauvegardes. Chaque exécution fonctionne comme [`verbatra translate`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md), sauf que `watch` n'a pas de `--dry-run`, `--prune`, `--include-human`, `--estimate` ni `--max-tokens` et ne sort jamais avec `3`. Au démarrage, il ajoute aussi les entrées manquantes à un `.gitignore` existant, voir [Entrées du .gitignore](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#entrées-du-gitignore). ## Synopsis [#synopsis] ```bash verbatra watch [flags] ``` ## Exemples [#exemples] ```bash # surveiller et retraduire à chaque changement verbatra watch # plus calme dans un éditeur agité : attendre 1 s après le dernier changement, émettre du NDJSON verbatra watch --debounce 1000 --json # ne garder à jour que l'allemand pendant que tu travailles verbatra watch --locales de ``` ## Options [#options] | Option | Argument | Défaut | Effet | | --- | --- | --- | --- | | `--locales` | `` | chaque locale cible configurée | ne surveille que ce sous-ensemble séparé par des virgules ; vérifié une fois au démarrage, où une locale non configurée échoue avec `UNKNOWN_LOCALE` | | `--debounce` | `` | `300` | attend ce nombre de millisecondes après le dernier changement avant de traduire ; un entier de `1` à `60000` | | `--lock-timeout` | `` | `600` | à chaque exécution, attend ce délai un verrou d'écriture occupé d'une locale ; un entier de `1` à `3600` | | `--concurrency` | `` | `1` | traduit jusqu'à `n` locales cibles à la fois par exécution ; un entier de `1` à `100`, refusé avec un budget `maxTokens` | | `--no-cache` | aucun | désactivé (cache actif) | contourne le [cache de mémoire de traduction](https://verbatra.kreitz-webdev.de/fr/docs/the-cache.md) (`verbatra.cache.json`) à chaque exécution | Accepte aussi les [options globales](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#options-globales) `--cwd`, `--config` et `--json` ; ici `--json` affiche un enregistrement par exécution. Avant de démarrer, `watch` charge les [fichiers d'environnement](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#fichiers-denvironnement). ## Comportement [#comportement] ### Chaque exécution [#chaque-exécution] Chaque exécution traduit le sous-ensemble `--locales`, ou toutes les cibles, avec un budget de tokens neuf. Une locale dont le [verrou d'écriture](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md) reste occupé au-delà de `--lock-timeout` échoue avec `LOCK_CONTENDED` dans le résumé de cette exécution, pendant que les autres continuent ; un verrou laissé par un processus verbatra qui ne tourne plus est récupéré aussitôt. Une exécution en échec n'arrête jamais la surveillance. L'attente d'un verrou affiche la même ligne d'attente que celle décrite sous [`translate`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md#verrous-décriture-et-interruptions). Un `--concurrency` supérieur à `1` avec un budget `maxTokens` configuré est refusé au démarrage avec la sortie `2`, avant la première exécution, car l'ordre dans lequel les locales s'entrelacent déciderait laquelle perd son travail restant. Un fournisseur impossible à construire, le plus souvent parce que sa variable de clé d'API manque, est lui aussi refusé au démarrage : `watch` sort avec `2` et `PROVIDER_CONSTRUCTION_FAILED` et une ligne `next:` qui nomme la variable, exactement comme `translate`, au lieu d'attendre des changements qu'aucune exécution ne pourrait traduire. Avant 0.12.0, il continuait d'attendre. ### Arrêt [#arrêt] La première interruption (Ctrl-C ou SIGTERM) laisse l'exécution en cours se terminer, arrête la surveillance et sort avec `0`. Une seconde interruption pendant que l'arrêt est encore en cours force l'arrêt avec la sortie `130`, après avoir libéré les verrous d'écriture de la session. Sans `--json`, stderr affiche `verbatra: waiting for changes...` après chaque exécution, `verbatra: press Ctrl-C to stop` après la ligne de démarrage dans un terminal interactif, et `verbatra: stopped` une fois l'arrêt terminé. `--quiet` supprime ces lignes, mais pas la ligne de démarrage ni `verbatra: stopping, finishing current run...` à la première interruption : elles sont écrites dans tous les modes, `--json` compris. ### Sortie JSON [#sortie-json] Schéma : [`watch-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/watch-envelope.json) valide l'enveloppe entière ; [Schémas](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#schémas) liste les autres. Avec `--json`, stdout est du NDJSON : une [enveloppe](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-json) par exécution, avec `command: "watch"`. Une exécution réussie est un enregistrement `ok: true` portant le [`RunSummary`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md#sortie-json) de cette exécution ; une exécution en échec est un enregistrement `ok: false` avec le code propre de l'échec, ou `WATCH_RUN_FAILED` s'il n'en avait pas, plus son `hint` s'il y en a un. Une exécution en échec n'est qu'un enregistrement : elle n'arrête pas la surveillance et ne change pas le code de sortie. La ligne de démarrage, l'avis d'arrêt et la progression vont sur stderr. Sans `--json`, le résumé d'une exécution va sur stdout et la ligne `verbatra: error [CODE] message` d'une exécution en échec sur stderr. ### Retour dans le terminal [#retour-dans-le-terminal] Sans `--json`, `watch` nomme le fichier source une fois qu'un changement s'est stabilisé, puis rend compte de l'exécution comme `translate`, avec le même spinner dans un terminal interactif : ```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... ``` Ces lignes vont sur stderr, et `--quiet` les supprime. Voir [Sortie dans le terminal](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-dans-le-terminal). ## Codes de sortie [#codes-de-sortie] | Code | Signification | | --- | --- | | `0` | arrêté proprement par une seule interruption | | `2` | impossible de démarrer ou de s'arrêter : une erreur de configuration, un échec au démarrage ou à l'arrêt, ou une erreur d'utilisation comme un `--debounce` invalide | | `130` | arrêt forcé par une seconde interruption | Une exécution en échec pendant la session ne change jamais le code de sortie. Voir [le contrat des codes de sortie](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#codes-de-sortie). ## Voir aussi [#voir-aussi] - [`verbatra translate`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md) est l'exécution unique que `watch` répète. - [Le cache](https://verbatra.kreitz-webdev.de/fr/docs/the-cache.md) explique ce que `--no-cache` contourne à chaque exécution. - [Comment ça marche](https://verbatra.kreitz-webdev.de/fr/docs/how-it-works.md) explique ce que fait chaque exécution. - [Protéger les traductions humaines](https://verbatra.kreitz-webdev.de/fr/docs/protecting-human-translations.md) explique pourquoi une exécution conserve une valeur obsolète écrite par une personne. - [La référence du SDK](https://verbatra.kreitz-webdev.de/fr/docs/sdk.md) documente les formes `WatchRunResult` et `RunSummary`.