--- title: "verbatra translate" description: "Traduit chaque locale cible une fois : seules les clés nouvelles et modifiées partent chez ton fournisseur, puis la commande écrit les résultats et termine." type: "reference" --- # verbatra translate Traduit chaque locale cible une fois : seules les clés nouvelles et modifiées partent chez ton fournisseur, puis la commande écrit les résultats et termine. Lance une passe de traduction sur chaque locale cible, puis termine. `translate` compare la source au [fichier de verrouillage](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md), n'envoie au fournisseur que les chaînes nouvelles ou modifiées, exécute les [contrôles d'intégrité](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md), écrit les fichiers de locale et met à jour le verrou. Une chaîne inchangée n'est jamais envoyée deux fois. Une vraie exécution 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 translate [flags] ``` ## Exemples [#exemples] ```bash # traduire une fois avec la configuration trouvée verbatra translate # voir les clés qui seraient retirées, sans rien dépenser verbatra translate --prune --dry-run # une locale à la fois, ce qu'exige une offre gratuite limitée en débit verbatra translate --locales de # dimensionner et chiffrer l'exécution sans rien dépenser verbatra translate --estimate # s'arrêter avant que l'exécution ne dépasse 50000 tokens verbatra translate --max-tokens 50000 # retraduire aussi les clés obsolètes écrites par une personne verbatra translate --include-human ``` ## Options [#options] | Option | Argument | Défaut | Effet | | --- | --- | --- | --- | | `--locales` | `` | chaque locale cible configurée | ne traduit que ce sous-ensemble séparé par des virgules ; une locale non configurée échoue avec `UNKNOWN_LOCALE` et une liste vide avec `INVALID_LOCALES`, les deux avec la sortie `2` | | `--dry-run` | aucun | désactivé | indique ce qu'une exécution changerait sans appeler de fournisseur ni écrire de fichier ; aucune clé d'API nécessaire | | `--prune` | aucun | l'option `prune` de la configuration, sinon désactivé | retire les clés orphelines (dans un fichier cible, absentes de la source) du fichier écrit et du verrou | | `--lock-timeout` | `` | `600` | 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 ; un entier de `1` à `100`, refusé avec un budget de tokens | | `--max-tokens` | `` | le `maxTokens` de la configuration | plafond strict de tokens pour cette exécution, un entier positif (sinon `INVALID_MAX_TOKENS`) ; la plus basse valeur entre celle-ci et `maxTokens` s'applique | | `--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`) pour cette exécution | | `--include-human` | aucun | désactivé | retraduit aussi, pour cette exécution seulement, les clés obsolètes écrites ou importées par une personne ; les [clés épinglées](https://verbatra.kreitz-webdev.de/fr/docs/protecting-human-translations.md#épingler-des-clés) restent intactes | | `--estimate` | aucun | désactivé | estime ce que l'exécution enverrait et coûterait, puis termine ; implique `--dry-run` | Accepte aussi les [options globales](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#options-globales) `--cwd`, `--config` et `--json`. Avant de s'exécuter, `translate` charge les [fichiers d'environnement](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#fichiers-denvironnement). ## Comportement [#comportement] Une exécution sans `--dry-run` ni `--estimate` envoie chaque chaîne nouvelle ou modifiée au fournisseur, et un fournisseur hébergé la facture : estime l'exécution avec `--estimate` et plafonne-la avec `--max-tokens`. Une clé d'API envoyée à un serveur auto-hébergé en `http://` simple (hors loopback) traverse le réseau en clair, voir [Les clés sont optionnelles](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#les-clés-sont-optionnelles). ### Exécution à blanc [#exécution-à-blanc] `--dry-run` ne construit aucun fournisseur : il n'a besoin d'aucune clé d'API et ne peut rien dépenser. Il lit les fichiers source et cibles, les compare au fichier de verrouillage et indique exactement ce qu'une vraie exécution changerait. Il n'écrit rien (ni fichier de locale, ni mise à jour du verrou, ni instantané d'état d'exécution), avec un fournisseur automatique ne lit ni n'écrit le cache (avec le fournisseur `none`, il lit la mémoire de traduction, voir plus bas) et ne prend aucun verrou d'écriture, donc n'attend jamais une exécution en cours. Par défaut, une exécution ne supprime rien : les clés orphelines sont signalées et restent en place. `--prune`, ou `prune: true` dans la config, supprime exactement ces clés des fichiers cibles et du verrou ; `--prune --dry-run` te les montre avant. ### Estimation du coût [#estimation-du-coût] `--estimate` ajoute à l'exécution à blanc une estimation préalable : combien de clés seraient envoyées, combien de requêtes au fournisseur cela ferait et la quantité que le fournisseur facture (des tokens pour un LLM ou un point d'accès `openai-compatible`, des caractères source pour DeepL, Google Cloud Translation ou LibreTranslate ; un point d'accès ou un serveur auto-hébergé n'est pas facturé, donc l'estimation n'indique aucun coût d'API). Un montant n'apparaît que si la configuration contient un bloc `rates` couvrant le fournisseur et le modèle ; sinon, la clé de tarif manquante est nommée au lieu d'inventer `0.00`. Voir [Estimer le coût](https://verbatra.kreitz-webdev.de/fr/docs/estimating-cost.md). ### Un sous-ensemble de locales [#un-sous-ensemble-de-locales] `--locales de,fr` limite l'exécution à une partie des cibles configurées. Les autres locales gardent leurs fichiers, leurs entrées de verrou et leurs entrées de cache. Utilise-le sur une offre gratuite limitée en débit pour traduire une locale à la fois, ou pour relancer une seule locale restée partielle. L'instantané d'état d'exécution ne décrit alors que ce sous-ensemble. ### Verrous d'écriture et interruptions [#verrous-décriture-et-interruptions] Une locale attend jusqu'à `--lock-timeout` un [verrou d'écriture](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md#le-verrou-décriture) occupé, puis échoue avec `LOCK_CONTENDED` pendant que les autres locales continuent. Un verrou laissé par un processus verbatra qui ne tourne plus sur cette machine est récupéré aussitôt. Le délai ne borne que cette attente, avant tout appel au fournisseur : l'inscription d'un fichier écrit dans le fichier de verrouillage attend toujours jusqu'au défaut de dix minutes, pour qu'aucun fichier écrit ne reste non enregistré. Une attente de plus d'une seconde affiche sur stderr une ligne qui nomme le verrou et son détenteur (avec `--json`, un enregistrement `lock-wait`), et `--quiet` ne la supprime pas. Ctrl-C ou SIGTERM libère les verrous de l'exécution avant que la commande ne se termine. ### Plafond de tokens [#plafond-de-tokens] `--max-tokens` est toujours un arrêt strict : une requête qui dépasserait le plafond est retenue, quoi que dise `budgetBehavior`, et ses clés figurent sous `budgetWithheld`. Il se compte comme un [budget `maxTokens`](https://verbatra.kreitz-webdev.de/fr/docs/config-file.md#maxtokens-et-budgetbehavior) configuré et peut resserrer ce budget, jamais l'assouplir. Une exécution coupée par le plafond sort avec `1`. Lance d'abord `--estimate` pour choisir une valeur. ### Locales en parallèle [#locales-en-parallèle] `--concurrency` est refusé avec la sortie `2` quand un budget de tokens s'applique (via `maxTokens` ou `--max-tokens`), car l'ordre dans lequel les locales s'entrelacent déciderait laquelle perd son travail restant ; une exécution à blanc en est exemptée. Si une erreur de toute l'exécution, comme un fichier de verrouillage corrompu, survient pendant que des locales tournent, aucune autre ne démarre, et celles en cours se terminent et libèrent leurs verrous avant que la commande ne sorte avec `2`. ### Clés écrites par une personne [#clés-écrites-par-une-personne] Une clé obsolète dont la valeur a été écrite, importée ou modifiée par une personne hors de verbatra est conservée par défaut : elle figure sous `protected`, n'est pas envoyée au fournisseur et reste obsolète pour `verbatra check`. Un avertissement sur stderr indique combien ont été conservées (les clés épinglées ne comptent pas) et renvoie à `--include-human`, qui les retraduit pour une exécution (`humanEdits: "overwrite"`) et n'affiche donc pas l'avertissement. Les clés protégées ne changent pas le code de sortie, sauf dans un projet entièrement humain. Voir [Protéger les traductions humaines](https://verbatra.kreitz-webdev.de/fr/docs/protecting-human-translations.md). ### Projets entièrement humains [#projets-entièrement-humains] Dans un projet [entièrement humain](https://verbatra.kreitz-webdev.de/fr/docs/human-only-workflow.md) (`provider: { id: "none" }`), aucun fournisseur n'est appelé. Les clés couvertes par la mémoire de traduction sont écrites, et toute autre clé manquante ou modifiée figure sous `unfilled` et donne la sortie `3` ; une locale en échec ou partielle l'emporte toujours avec `1`. Ici, une exécution à blanc lit la mémoire, donc son plan montre les mêmes clés `cacheHits` et `unfilled`, et `--estimate` n'indique rien de facturé ; les deux sortent avec `3` de la même façon. Sans `--json`, un avertissement sur stderr indique combien de clés ont besoin d'une personne, et une indication `next:` renvoie à [`verbatra export`](https://verbatra.kreitz-webdev.de/fr/docs/cli/export.md), avec lequel tu transmets les clés `unfilled`. ### Locales en échec et partielles [#locales-en-échec-et-partielles] L'échec d'une locale n'est pas fatal : l'exécution se termine et sort avec `1`. Une locale **partielle** sort aussi avec `1` : son fichier a été écrit mais des clés manquent encore, en général parce qu'un sous-lot du fournisseur a échoué ou que le contrôle d'intégrité a refusé une traduction. La sortie lisible liste chaque clé refusée sous `integrity-withheld` avec sa raison (`placeholder`, `markup`, `icu`, `degenerate` ou `empty`) ; avec `--json`, chaque locale les porte dans `integrityRefusals`. Les clés que l'exécution a signalées pour relecture suivent le compte `N needs-review` de la locale sous une ligne `needs-review:`, chacune avec ses [raisons de relecture](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md#signalements-de-relecture) ; avec `--json`, elles sont dans `needsReview`. ### Locales non prises en charge [#locales-non-prises-en-charge] Une locale que le fournisseur DeepL ou Google Cloud Translation configuré ne prend pas en charge refuse toute l'exécution avec `LOCALE_UNSUPPORTED_BY_PROVIDER` et la sortie `2`, aussi à blanc et avec `--estimate`, avant toute dépense. Laisse-la de côté avec `--locales`, ou consulte [Prise en charge des langues](https://verbatra.kreitz-webdev.de/fr/docs/language-support.md#vérifier-la-prise-en-charge-avant-une-exécution). Un glossaire ou un ton que le fournisseur ne sait pas appliquer ne fait qu'ajouter un avis (`GLOSSARY_UNSUPPORTED_BY_PROVIDER`, `FORMALITY_UNSUPPORTED_BY_PROVIDER`), tout comme `LOCALE_UNVERIFIED_BY_PROVIDER` et, pour un LLM, `LOCALE_NOT_WELL_TESTED`. ### Sortie JSON [#sortie-json] Schéma : [`translate-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/translate-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 porte une [enveloppe](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-json) dont le `result` est un `RunSummary` ; [RunSummary](https://verbatra.kreitz-webdev.de/fr/docs/sdk/run-summary.md) liste chaque champ, de l'exécution et de chaque locale. ### Retour dans le terminal [#retour-dans-le-terminal] `translate` nomme les locales et le fournisseur avant l'exécution, puis affiche la durée, les tokens utilisés et la commande suivante. Dans un terminal interactif, la progression tient sur une ligne avec spinner ; quand stderr est redirigé, chaque étape est une ligne à part : ```text output verbatra: translating 2 locales with gemini/gemini-2.5-flash verbatra: translating de verbatra: de batch 1/1 verbatra: de: writing verbatra: de done, 12 translated verbatra: translating fr verbatra: fr batch 1/1 verbatra: fr: writing verbatra: fr done, 12 translated verbatra: run finished, 2 locales processed [ok] done in 4.2s, 1830 tokens next: verbatra check (confirm every locale is in sync) ``` Une exécution à blanc commence par `dry run over 2 locales, no provider call`, une estimation par `estimating 2 locales, no provider call` et un projet entièrement humain par `filling 2 locales from the translation memory (provider none)`. Une exécution à blanc ou une estimation termine chaque locale par `would translate`. Une locale qui n'a gardé qu'une partie des clés se termine par `partly done`, une locale en échec par `failed`, et la ligne finale indique combien ont échoué. Une exécution à blanc se termine par `dry run done in 4.2s, nothing written`. Une estimation se termine par `estimate done in 4.2s, nothing written` . 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` | chaque locale cible est complète | | `1` | l'exécution s'est terminée, mais une locale a échoué ou est partielle | | `2` | impossible de s'exécuter : une erreur de configuration, de source, de format, de fournisseur, de locale non prise en charge ou de fichier de verrouillage, ou une erreur d'utilisation | | `3` | projet entièrement humain : l'exécution (exécution à blanc et `--estimate` compris) s'est terminée proprement, mais des clés attendent une traduction humaine | | `130` | interrompu avec Ctrl-C (SIGINT) après libération des verrous d'écriture | | `143` | arrêté avec SIGTERM après libération des verrous d'écriture | Après une interruption, stderr se termine par `verbatra: interrupted (SIGINT), released locks`, ou avec `--json` par l'enregistrement `{"type":"interrupted","signal":"SIGINT","locksReleased":true}`. Si la libération des verrous échoue ou ne se termine pas en 5 secondes, la ligne le dit à la place (`could not release locks: ` ou `lock release did not finish within 5s`), et l'enregistrement JSON porte `"locksReleased":false` avec `"reason":"failed"` (plus `message`) ou `"reason":"timed-out"` (plus `deadlineMs`). Voir [le contrat des codes de sortie](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#codes-de-sortie). ## Voir aussi [#voir-aussi] - [Comment ça marche](https://verbatra.kreitz-webdev.de/fr/docs/how-it-works.md) explique la chaîne lecture, comparaison, traduction, écriture. - [Le cache](https://verbatra.kreitz-webdev.de/fr/docs/the-cache.md) explique ce que `--no-cache` contourne. - [Sécurité des traductions](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md) couvre les contrôles d'intégrité et la file de relecture. - [`verbatra diff`](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md) montre les mêmes clés en attente, en lecture seule. - [CI et codes de sortie](https://verbatra.kreitz-webdev.de/fr/docs/ci-and-exit-codes.md) montre comment réagir à ces codes dans un pipeline.