Dépannage

Chaque entrée part de ce que tu vois et relie le code qui se cache derrière à Codes d'erreur, où chaque code figure avec sa signification, son code de sortie et son étape suivante. Cherche le code de verbatra: error [CODE], jamais le texte du message.

Lance verbatra doctor avant de passer les entrées une à une : il vérifie la config, le format, le fournisseur, la variable de la clé d'API et le fichier source en une seule passe, ne dépense rien et fonctionne avant même que le fichier de locale source existe.

pnpm bloque les scripts d'installation d'une dépendance (ERR_PNPM_IGNORED_BUILDS)Copier le lien vers cette section

Symptôme : pnpm add -D @verbatra/cli affiche son résumé d'installation puis sort avec 1 :

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: @google/genai@3.1.0, protobufjs@7.6.5
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

pnpm écrit aussi un pnpm-workspace.yaml dans ton projet, contenant un choix sans réponse :

allowBuilds:
  '@google/genai': set this to true or false
  protobufjs: set this to true or false

Tant que tu n'y réponds pas, chaque commande pnpm suivante dans ce projet échoue de la même façon, y compris pnpm exec verbatra init.

Cause : pnpm n'exécute les scripts d'installation d'une dépendance tierce que si tu l'autorises. @google/genai et son protobufjs transitif déclarent de tels scripts, et le SDK Gemini est installé quel que soit le fournisseur configuré, donc chaque installation pnpm y passe. verbatra ne déclare aucun script d'installation à lui, et npm et yarn installent le même paquet sans rien demander. L'installation a bien abouti : node_modules/.bin/verbatra fonctionne déjà.

Solution : réponds une fois au choix. En interactif, lance pnpm approve-builds et n'approuve aucune des deux entrées. En non interactif, ce que tu veux en CI, écris la réponse avant d'installer en mettant ceci dans le pnpm-workspace.yaml à la racine du projet :

allowBuilds:
  '@google/genai': false
  protobufjs: false

verbatra n'a pas besoin de ces scripts, et ce dépôt les refuse tous les deux. Une fois la réponse en place, pnpm add -D @verbatra/cli sort avec 0 et les commandes pnpm suivantes s'exécutent normalement. Les versions de paquets du message suivent la release ; la solution ne change pas.

La configuration est invalide (CONFIG_INVALID)Copier le lien vers cette section

Symptôme : The verbatra configuration is invalid: ..., avec un problème par champ.

Cause : la config a été trouvée, mais échoue à la validation, par exemple un files.pattern sans {locale}, un code de locale qui n'est pas du BCP 47 (comme en_US) ou une clé inconnue. Une clé inconnue reçoit la note API keys are read from the environment, not the config : le schéma est strict pour qu'aucun secret ne se cache dans un fichier commité.

Solution : corrige le champ que nomme le message ; voir Fichier de configuration. Pour No verbatra configuration found..., voir CONFIG_NOT_FOUND. Code : CONFIG_INVALID.

Aucun adaptateur pour le format (UNKNOWN_FORMAT)Copier le lien vers cette section

Symptôme : No adapter is registered for format "...", suivi de la liste des formats pris en charge.

Cause : le format de la config n'est pas un id enregistré. Un format custom: ne tourne pas en ligne de commande, qui ne charge aucun plugin.

Solution : utilise un id de Formats. Pour un format custom:, passe par le SDK avec un registre qui contient son adaptateur : voir Écrire un adaptateur de format personnalisé. Code : UNKNOWN_FORMAT.

La locale demandée n'est pas configurée (UNKNOWN_LOCALE)Copier le lien vers cette section

Symptôme : Requested locale not in the configured target locales: ...

Cause : --locales (ou une entrée locales du SDK) nomme une locale absente de targetLocales. Un filtre choisit dans la liste configurée ; il ne l'étend jamais.

Solution : ajoute la locale à targetLocales, ou corrige la faute de frappe. Code : UNKNOWN_LOCALE.

Le fichier source est absent ou impossible à analyser (SOURCE_UNREADABLE, SOURCE_INVALID)Copier le lien vers cette section

Symptôme : The source locale file was not found at <path>. ou The source locale file at <path> could not be read: ...

Cause : files.pattern avec la locale source insérée ne mène à aucun fichier, ou le fichier ne se parse pas. Le chemin est résolu depuis la racine du projet, le répertoire de la config trouvée (ou le répertoire de travail avec --config), donc un --cwd ou un --config erroné est une cause fréquente, tout comme un joker : files.pattern est un chemin littéral, pas un glob (voir Dispositions avec espaces de noms).

Solution : vérifie le chemin affiché. En cas d'échec d'analyse, le causeCode nomme le code de l'adaptateur de format. Codes : SOURCE_UNREADABLE, SOURCE_INVALID.

Clé d'API manquante (PROVIDER_CONSTRUCTION_FAILED)Copier le lien vers cette section

Symptôme : Failed to construct provider "anthropic": The ANTHROPIC_API_KEY environment variable is not set. (ou la variable de ton fournisseur).

Cause : la variable que nomme le message n'est pas définie ou est vide. Les clés viennent uniquement de l'environnement, jamais de la config ni d'une option.

Solution : définis la variable et confirme-la avec verbatra doctor. La CLI la lit aussi depuis .env.local et .env ; le SDK non, donc utilise node --env-file=.env dans ton propre script. Codes : PROVIDER_CONSTRUCTION_FAILED, MISSING_API_KEY.

Limites de débit, délais et échecs d'authentification en cours d'exécution (RATE_LIMITED, TIMEOUT, AUTH_FAILED)Copier le lien vers cette section

Symptôme : l'exécution se termine, mais certaines clés figurent sous providerFailures avec un avis SUB_BATCH_FAILED qui nomme le code du fournisseur, et la commande sort avec 1.

Cause : une requête au fournisseur a échoué après sa construction : HTTP 429, un délai dépassé ou HTTP 401/403.

Solution : rien n'est perdu ; les clés sont reprises à la prochaine exécution. Avec RATE_LIMITED, relance plus tard, après l'attente que nomme le message s'il en nomme une (un quota quotidien épuisé), et une locale à la fois avec --locales si le quota est strict. Pour un modèle lent, relève requestTimeoutMs face à TIMEOUT. AUTH_FAILED ne se règle pas en réessayant : remplace la clé.

Le fichier de verrouillage est corrompu (LOCK_FILE_INVALID)Copier le lien vers cette section

Symptôme : The lock-file at <path> is not valid JSON., ... has an unexpected shape., ... has version N ... ou ... exceeds the maximum allowed size ...

Cause : verbatra.lock.json a été modifié à la main, tronqué, abîmé dans un merge ou écrit par une version incompatible. translate et import arrêtent toute l'exécution à cause de lui, et les locales validées avant l'arrêt gardent ce qu'elles ont écrit.

Solution : restaure le fichier depuis le contrôle de version. Le supprimer efface aussi l'erreur, mais perd les références, donc les modifications antérieures de la source ne sont plus détectées comme obsolètes. Voir Le fichier de verrouillage. Code : LOCK_FILE_INVALID.

Un fichier de locale n'a pas pu être écrit (TARGET_UNWRITABLE)Copier le lien vers cette section

Symptôme : une locale échoue avec Could not write the locale file locales/de.json (EACCES). ...

Cause : le fichier ou son répertoire n'est pas accessible en écriture : droits, répertoire absent, montage en lecture seule ou disque plein. L'écriture passe par un fichier temporaire dans le même répertoire, donc le répertoire doit aussi être accessible en écriture.

Solution : corrige ce que nomme le code du système de fichiers et relance. Seule cette locale échoue, et elle garde son fichier et sa référence précédents. Code : TARGET_UNWRITABLE.

Un autre processus détient le verrou d'écriture (LOCK_CONTENDED)Copier le lien vers cette section

Symptôme : Could not acquire the write lock at <path>: another process is holding it. ...

Cause : un autre translate, watch, import ou une écriture de Studio détient le verrou de la locale. Un verrou laissé par un processus mort sur cette machine est récupéré automatiquement, donc un verrou qui persiste vient d'une autre machine ou d'un verbatra antérieur à 0.12.0.

Solution : attends l'autre exécution, ou supprime le fichier de verrou affiché si aucun processus verbatra ne tourne nulle part. --lock-timeout <seconds> sur translate, watch et import change combien de temps une exécution attend. Code : LOCK_CONTENDED.

Des clés à points ou des clés YAML entrent en collision (INVALID_STRUCTURE)Copier le lien vers cette section

Symptôme : A dotted key and a nested key path resolve to the same path. ou, pour YAML, A mapping key is a map or sequence (expected scalar keys).

Cause : deux entrées d'un fichier mènent à la même clé, comme "a.b" à côté de a: { b: ... }, ou une clé YAML n'a pas de forme de chaîne. verbatra refuse plutôt que d'en abandonner une.

Solution : renomme l'une des clés, ou utilise une clé YAML scalaire. Dans le fichier source, cela arrive enveloppé dans SOURCE_INVALID. Code : INVALID_STRUCTURE.

L'exécution s'est arrêtée avant certaines clés (budget de tokens)Copier le lien vers cette section

Symptôme : un avis BUDGET_TOKENS_EXCEEDED ; avec budgetBehavior: "stop", des clés figurent aussi sous budgetWithheld.

Cause : l'exécution a atteint maxTokens dans la config ou --max-tokens pour l'exécution. "warn" ne signale qu'un budget venu de la config ; "stop", et --max-tokens quoi que dise la config, retiennent chaque clé pas encore tentée, et la locale se termine en partial ou failed.

Solution : c'est le garde-fou qui fonctionne : ce qui est arrivé est écrit, et les clés retenues sont traduites à la prochaine exécution. Relève le budget ou passe à "warn" pour tout terminer en une exécution. Le calcul du budget est décrit dans Sécurité des traductions. Code : BUDGET_TOKENS_EXCEEDED.

Une traduction est retenue à cause du balisage en ligne (discordance d'intégrité)Copier le lien vers cette section

Symptôme : une clé figure sous integrityMismatches et garde sa valeur précédente, ou Studio affiche Rejected: inline markup mismatch avec les balises en cause : -<a href> pour une balise que le candidat a perdue, +<i> pour une qu'il a inventée. verbatra check --qa signale la même chose pour les valeurs déjà sur disque.

Cause : le candidat ne porte pas les balises en ligne de la source, ou les porte déséquilibrées ou mal imbriquées, donc la barrière d'intégrité le refuse comme un placeholder perdu.

Solution : relance la clé, ou corrige la valeur à la main dans Studio ou dans un classeur ; la même barrière juge les deux. Ce qui est comparé et quels refus sont voulus est décrit dans Parité du balisage en ligne.

Studio : le port est déjà utiliséCopier le lien vers cette section

Symptôme : port 5849 is already in use (ou ta valeur de --port).

Cause : un autre processus, souvent un Studio précédent, occupe le port.

Solution : arrête-le, ou démarre Studio sur un autre port : verbatra studio --port 6000.

Studio : @verbatra/studio n'est pas installéCopier le lien vers cette section

Symptôme : Verbatra Studio requires @verbatra/studio., suivi des commandes d'installation.

Cause : Studio est un paquet séparé que la commande studio charge à la demande.

Solution : npm install --save-dev @verbatra/studio, ou pour une exécution ponctuelle npx -y -p @verbatra/cli -p @verbatra/studio verbatra studio. Avec pnpm, lis d'abord pnpm bloque les scripts d'installation d'une dépendance.

npx @verbatra/cli lance la CLI installée dans le paquet du dossier courant, donc lance-le depuis la racine du projet (ou utilise pnpm exec verbatra dans un sous-paquet du workspace) ; ailleurs, npx télécharge la dernière CLI, qui peut ne pas correspondre à ton @verbatra/studio ou @verbatra/mcp local.

Studio : les actions de retraduction et de traduction manquentCopier le lien vers cette section

Symptôme : l'édition fonctionne, mais les actions de retraduction et de traduction des clés en attente n'apparaissent pas.

Cause : la dépense chez le fournisseur s'accorde au démarrage, selon les règles de Dépenses et outils d'agent, et sans cette autorisation les actions de dépense ne sont pas enregistrées.

Solution : redémarre avec verbatra studio --allow-spend, sauf si le projet est uniquement humain. Voir Réviser dans Studio.

MCP : @verbatra/mcp n'est pas installéCopier le lien vers cette section

Symptôme : Verbatra's MCP server requires @verbatra/mcp., suivi des commandes d'installation.

Cause : le serveur MCP est un paquet séparé que la commande mcp charge à la demande, donc npx -y @verbatra/cli mcp seul ne fonctionne jamais.

Solution : lance npx -y @verbatra/mcp, ou installe @verbatra/mcp à côté de la CLI et relance verbatra mcp. Avec pnpm, lis d'abord pnpm bloque les scripts d'installation d'une dépendance.

MCP : le tools/list d'un agent ne montre jamais translation.retranslateEntry ni translation.translatePendingCopier le lien vers cette section

Symptôme : les outils locaux fonctionnent, mais les deux outils de dépense manquent, et en appeler un par son nom échoue comme outil inconnu.

Cause : la dépense s'accorde au démarrage, selon les règles des Outils payants, et la liste d'outils ne doit pas changer selon la connexion, donc les outils de dépense sont entièrement laissés de côté.

Solution : redémarre avec verbatra mcp --allow-spend, sauf si le projet est uniquement humain.

Annuler une exécution (aucun code d'erreur)Copier le lien vers cette section

verbatra n'a pas de commande d'annulation ; le contrôle de version est le chemin du retour. Rétablis les fichiers de locale, verbatra.lock.json et verbatra.provenance.json ensemble, jamais les fichiers de locale seuls. Voir Récupération et retour en arrière.