verbatra translate

Lance une passe de traduction sur chaque locale cible, puis termine. translate compare la source au fichier de verrouillage, n'envoie au fournisseur que les chaînes nouvelles ou modifiées, exécute les contrôles d'intégrité, é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.

SynopsisCopier le lien vers cette section

verbatra translate [flags]

ExemplesCopier le lien vers cette section

# 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

OptionsCopier le lien vers cette section

Accepte aussi les options globales --cwd, --config et --json. Avant de s'exécuter, translate charge les fichiers d'environnement.

ComportementCopier le lien vers cette section

Exécution à blancCopier le lien vers cette section

--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.

Estimation du coûtCopier le lien vers cette section

--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.

Un sous-ensemble de localesCopier le lien vers cette section

--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 interruptionsCopier le lien vers cette section

Une locale attend jusqu'à --lock-timeout un 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 tokensCopier le lien vers cette section

--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 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èleCopier le lien vers cette section

--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 personneCopier le lien vers cette section

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.

Projets entièrement humainsCopier le lien vers cette section

Dans un projet entièrement humain (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, avec lequel tu transmets les clés unfilled.

Locales en échec et partiellesCopier le lien vers cette section

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 ; avec --json, elles sont dans needsReview.

Locales non prises en chargeCopier le lien vers cette section

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. 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 JSONCopier le lien vers cette section

Schéma : translate-envelope.json valide l'enveloppe entière ; Schémas liste les autres.

Avec --json, stdout porte une enveloppe dont le result est un RunSummary ; RunSummary liste chaque champ, de l'exécution et de chaque locale.

Retour dans le terminalCopier le lien vers cette section

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 :

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 nouveau. Ces lignes vont sur stderr, et --quiet les supprime. Voir Sortie dans le terminal.

Codes de sortieCopier le lien vers cette section

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: <reason> 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.

Voir aussiCopier le lien vers cette section

• Comment ça marche explique la chaîne lecture, comparaison, traduction, écriture.
• Le cache explique ce que --no-cache contourne.
• Sécurité des traductions couvre les contrôles d'intégrité et la file de relecture.
• verbatra diff montre les mêmes clés en attente, en lecture seule.
• CI et codes de sortie montre comment réagir à ces codes dans un pipeline.