--- title: "Codes d'erreur" description: "Chaque code d'erreur, de résultat et d'avis que signale verbatra : ce qu'il signifie, quelles commandes le lèvent, le code de sortie et l'étape suivante." type: "reference" --- # Codes d'erreur Chaque code d'erreur, de résultat et d'avis que signale verbatra : ce qu'il signifie, quelles commandes le lèvent, le code de sortie et l'étape suivante. Chaque échec que signale verbatra porte un code stable : dans la ligne `verbatra: error [CODE] message` sur stderr, comme `code` ou `causeCode` d'une enveloppe `--json`, comme `error.code` d'une locale en échec, ou comme avis dans le résumé de l'exécution. Branche-toi sur le code, jamais sur le message. Chaque code a sa propre ancre, `/docs/error-codes#` suivi du code en minuscules, comme [`#config_not_found`](#config_not_found). L'**Étape suivante** d'un code d'erreur est l'indice que verbatra affiche après la ligne d'erreur sous la forme `next: ...` et place dans le champ `hint` de l'enveloppe. Il est cité ici exactement comme verbatra l'affiche, en anglais, et le SDK renvoie le même texte depuis [`errorHint`](https://verbatra.kreitz-webdev.de/fr/docs/sdk/errors.md#errorhint). Les codes de sortie eux-mêmes et la forme de l'enveloppe sont sur [Codes de sortie et sortie JSON](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md) ; l'aide à partir du symptôme est sur [Dépannage](https://verbatra.kreitz-webdev.de/fr/docs/troubleshooting.md). Deux codes appartiennent à deux familles : `CONFIG_INVALID` (le SDK, et `init` dans la CLI) et `NETWORK_POLICY_VIOLATION` (le SDK et les fournisseurs). L'ancre en minuscules mène à l'entrée du SDK ; l'autre entrée porte une ancre préfixée. ## Index des codes [#index-des-codes] Chaque code d'erreur avec sa famille et les codes de sortie avec lesquels il peut terminer une exécution de la CLI ; la section de sa famille dit lequel s'applique et quand. | Code | Famille | Code de sortie | | --- | --- | --- | | [`AGENT_FILE_INVALID`](#agent_file_invalid) | CLI | `2` | | [`CLI_ERROR`](#cli_error) | CLI | `2` | | [`CONFIG_EXISTS`](#config_exists) | CLI | `2` | | [`CONFIG_INVALID`](#cli-config_invalid) | CLI | `2` | | [`FORMAT_AMBIGUOUS`](#format_ambiguous) | CLI | `2` | | [`INIT_UNWRITABLE`](#init_unwritable) | CLI | `2` | | [`INVALID_CONCURRENCY`](#invalid_concurrency) | CLI | `2` | | [`INVALID_DEBOUNCE`](#invalid_debounce) | CLI | `2` | | [`INVALID_DIRECTION`](#invalid_direction) | CLI | `2` | | [`INVALID_FORMAT`](#invalid_format) | CLI | `2` | | [`INVALID_LOCALE`](#invalid_locale) | CLI | `2` | | [`INVALID_LOCALES`](#invalid_locales) | CLI | `2` | | [`INVALID_LOCK_TIMEOUT`](#invalid_lock_timeout) | CLI | `2` | | [`INVALID_MAX_TOKENS`](#invalid_max_tokens) | CLI | `2` | | [`INVALID_OPTION`](#invalid_option) | CLI | `2` | | [`INVALID_OUT`](#invalid_out) | CLI | `2` | | [`INVALID_PORT`](#invalid_port) | CLI | `2` | | [`INVALID_PROVIDER`](#invalid_provider) | CLI | `2` | | [`INVALID_QA_OPTION`](#invalid_qa_option) | CLI | `2` | | [`INVALID_SEVERITY`](#invalid_severity) | CLI | `2` | | [`LAYOUT_AMBIGUOUS`](#layout_ambiguous) | CLI | `2` | | [`MISSING_OPTIONS`](#missing_options) | CLI | `2` | | [`REDACTION_UNSUPPORTED`](#redaction_unsupported) | CLI | `2` | | [`USAGE_ERROR`](#usage_error) | CLI | `2` | | [`CONFIG_NOT_FOUND`](#config_not_found) | SDK | `2` ou `1` | | [`CONFIG_INVALID`](#config_invalid) | SDK | `2` ou `1` | | [`UNKNOWN_FORMAT`](#unknown_format) | SDK | `2` ou `1` | | [`UNKNOWN_LOCALE`](#unknown_locale) | SDK | `2` | | [`UNKNOWN_KEY`](#unknown_key) | SDK | aucun | | [`KEY_PROTECTED`](#key_protected) | SDK | aucun | | [`KEY_PINNED`](#key_pinned) | SDK | aucun | | [`PROVIDER_CONSTRUCTION_FAILED`](#provider_construction_failed) | SDK | `2` | | [`MACHINE_TRANSLATION_DISABLED`](#machine_translation_disabled) | SDK | aucun | | [`NETWORK_POLICY_VIOLATION`](#network_policy_violation) | SDK | `2` | | [`SOURCE_UNREADABLE`](#source_unreadable) | SDK | `2` ou `1` | | [`SOURCE_INVALID`](#source_invalid) | SDK | `2` ou `1` | | [`LOCK_FILE_INVALID`](#lock_file_invalid) | SDK | `2` | | [`PROVENANCE_FILE_INVALID`](#provenance_file_invalid) | SDK | `2` | | [`PROVENANCE_FILE_UNWRITABLE`](#provenance_file_unwritable) | SDK | aucun | | [`REVIEW_VALUE_CHANGED`](#review_value_changed) | SDK | aucun | | [`REVIEW_SOURCE_CHANGED`](#review_source_changed) | SDK | aucun | | [`REVIEW_REJECT_UNSUPPORTED`](#review_reject_unsupported) | SDK | aucun | | [`REVIEW_RESTORE_FAILED`](#review_restore_failed) | SDK | aucun | | [`REVIEWER_INVALID`](#reviewer_invalid) | SDK | `2` | | [`LOCK_CONTENDED`](#lock_contended) | SDK | `1` | | [`GLOSSARY_NOT_FILE_BACKED`](#glossary_not_file_backed) | SDK | aucun | | [`GLOSSARY_UNWRITABLE`](#glossary_unwritable) | SDK | aucun | | [`LOCALE_LAYOUT_INVALID`](#locale_layout_invalid) | SDK | `2` | | [`LOCALE_PATH_COLLISION`](#locale_path_collision) | SDK | `2` | | [`CONCURRENCY_INVALID`](#concurrency_invalid) | SDK | aucun | | [`CONCURRENCY_BUDGET_CONFLICT`](#concurrency_budget_conflict) | SDK | `2` | | [`MAX_TOKENS_INVALID`](#max_tokens_invalid) | SDK | aucun | | [`LOCK_TIMEOUT_INVALID`](#lock_timeout_invalid) | SDK | aucun | | [`PAGE_CURSOR_INVALID`](#page_cursor_invalid) | SDK | aucun | | [`PAGE_LIMIT_INVALID`](#page_limit_invalid) | SDK | aucun | | [`TARGET_UNWRITABLE`](#target_unwritable) | SDK | `1` ou `2` | | [`PSEUDO_OUTPUT_CONFLICT`](#pseudo_output_conflict) | SDK | `2` | | [`SOURCE_UNWRITABLE`](#source_unwritable) | SDK | `2` | | [`EXTRACT_NOT_CONFIGURED`](#extract_not_configured) | SDK | `2` | | [`EXTRACT_FS_UNSUPPORTED`](#extract_fs_unsupported) | SDK | aucun | | [`TYPES_OUTPUT_CONFLICT`](#types_output_conflict) | SDK | `2` | | [`TYPES_UNWRITABLE`](#types_unwritable) | SDK | `2` | | [`TMX_OUTPUT_CONFLICT`](#tmx_output_conflict) | SDK | `2` | | [`TMX_UNWRITABLE`](#tmx_unwritable) | SDK | `2` | | [`MEMORY_UNWRITABLE`](#memory_unwritable) | SDK | `2` | | [`EXPORT_OUTPUT_CONFLICT`](#export_output_conflict) | SDK | `2` | | [`EXPORT_UNWRITABLE`](#export_unwritable) | SDK | `2` | | [`LOCALE_STATE_NOT_CARRIED_OVER`](#locale_state_not_carried_over) | SDK | `1` | | [`LOCALE_UNSUPPORTED_BY_PROVIDER`](#locale_unsupported_by_provider) | SDK | `2` | | [`NOT_A_LOCALE_FILE`](#not_a_locale_file) | SDK | `2` | | [`SENSITIVE_CONTENT_WITHHELD`](#sensitive_content_withheld) | SDK | aucun | | [`RUN_CANCELLED`](#run_cancelled) | SDK | aucun | | [`LOCALE_FAILED`](#locale_failed) | SDK | `1` | | [`MISSING_API_KEY`](#missing_api_key) | Fournisseur | `2` | | [`INVALID_REQUEST`](#invalid_request) | Fournisseur | `1` | | [`INVALID_RESPONSE`](#invalid_response) | Fournisseur | `1` | | [`OUTPUT_TRUNCATED`](#output_truncated) | Fournisseur | `1` | | [`PROVIDER_REFUSED`](#provider_refused) | Fournisseur | `1` | | [`PROVIDER_BLOCKED`](#provider_blocked) | Fournisseur | `1` | | [`RATE_LIMITED`](#rate_limited) | Fournisseur | `1` | | [`TIMEOUT`](#timeout) | Fournisseur | `1` | | [`AUTH_FAILED`](#auth_failed) | Fournisseur | `1` | | [`PROVIDER_UNAVAILABLE`](#provider_unavailable) | Fournisseur | `1` | | [`NETWORK_POLICY_VIOLATION`](#provider-network_policy_violation) | Fournisseur | `1` | | [`PROVIDER_ERROR`](#provider_error) | Fournisseur | `1` | | [`INVALID_JSON`](#invalid_json) | Adaptateur de format | `1` ou `2` | | [`INVALID_YAML`](#invalid_yaml) | Adaptateur de format | `1` ou `2` | | [`INVALID_XML`](#invalid_xml) | Adaptateur de format | `1` ou `2` | | [`INVALID_STRUCTURE`](#invalid_structure) | Adaptateur de format | `1` ou `2` | | [`MAX_DEPTH_EXCEEDED`](#max_depth_exceeded) | Adaptateur de format | `1` ou `2` | | [`INPUT_TOO_LARGE`](#input_too_large) | Adaptateur de format | `1` ou `2` | | [`MIXED_STRUCTURE`](#mixed_structure) | Adaptateur de format | `1` ou `2` | | [`ADAPTER_FAILED`](#adapter_failed) | Adaptateur de format | aucun | | [`DUPLICATE_FORMAT`](#duplicate_format) | Adaptateur de format | aucun | | [`INVALID_FORMAT_ID`](#invalid_format_id) | Adaptateur de format | aucun | ## Codes d'erreur de la CLI [#cli-error-codes] La CLI lève ces codes elle-même. La même liste est publiée sous le nom `CLI_ERROR_CODES` (avec le type `CliErrorCode`) depuis `@verbatra/cli`. Tous sortent avec `2`. ### AGENT_FILE_INVALID [#agent_file_invalid] `init --agent` a trouvé une configuration de client (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json` ou `.gemini/settings.json`) qui n'est pas du JSON pur, n'est pas un objet ou contient une valeur de serveurs qui n'est pas un objet, un `.codex/config.toml` qu'il ne peut pas lire sans risque ou qui définit le serveur verbatra en ligne, avec des clés pointées, comme tableau de tables ou deux fois, un lien symbolique sur un chemin qu'il écrirait, ou un marqueur verbatra sans paire ou répété dans `AGENTS.md` ou `CLAUDE.md` ; rien n'a été écrit. - **Levé par** : `init --agent` - **Étape suivante** : Repair the MCP config or the verbatra markers in the file the message names, or replace the symbolic link it names with a plain file, then run `verbatra init --agent` again. ### CLI_ERROR [#cli_error] Un échec ne portait aucun code propre (le code de repli). - **Levé par** : n'importe quelle commande ### CONFIG_EXISTS [#config_exists] `init` écraserait un `verbatra.config.ts` différent sans `--force`, ou un autre fichier de config verbatra du répertoire serait lu en premier ; signalé avant toute réponse manquante ou ambiguë, et dans un terminal avant la première question. - **Levé par** : `init` - **Étape suivante** : Edit the existing config, or pass --force to replace verbatra.config.ts; remove any other config file the message names first. ### CONFIG_INVALID [#cli-config_invalid] `init` n'a pas pu générer une configuration valide à partir des réponses reçues (le SDK lève le même code pour une configuration qui ne se charge pas). - **Levé par** : `init` - **Étape suivante** : Correct the init answers the message names, then run `verbatra init` again. ### FORMAT_AMBIGUOUS [#format_ambiguous] `init` a trouvé plusieurs formats qui lisent les fichiers de locale ; `candidates` les liste. - **Levé par** : `init` - **Étape suivante** : Pass --format with one of the candidates. ### INIT_UNWRITABLE [#init_unwritable] `init` n'a pas pu écrire un fichier dans son répertoire, par exemple parce qu'il est en lecture seule ou qu'un fichier qu'il écrit est un lien symbolique qui ne se résout pas dans le projet ; le message nomme le fichier, la cause et les fichiers déjà écrits. - **Levé par** : `init` - **Étape suivante** : Make the directory writable, or replace the symbolic link the message names with a plain file, then run `verbatra init` again. ### INVALID_CONCURRENCY [#invalid_concurrency] `--concurrency` n'est pas un nombre entier de 1 à 100. - **Levé par** : `translate`, `watch` - **Étape suivante** : Pass --concurrency as a whole number from 1 to 100. ### INVALID_DEBOUNCE [#invalid_debounce] `watch --debounce` n'est pas un nombre entier de millisecondes de 1 à 60000. - **Levé par** : `watch` - **Étape suivante** : Pass --debounce as a whole number of milliseconds from 1 to 60000. ### INVALID_DIRECTION [#invalid_direction] `tmx` a reçu une direction autre que `import` ou `export`, ou `tmx export` a reçu une option réservée à l'import (`--dry-run`, `--overwrite`). - **Levé par** : `tmx` - **Étape suivante** : Run `verbatra tmx import` or `verbatra tmx export`, with only the flags that direction takes. ### INVALID_FORMAT [#invalid_format] `--format` sur `export` ou `import` ne nomme aucun format de remise pris en charge, ou `--format` sur `init` ne nomme aucun format de fichier de locale pris en charge. - **Levé par** : `export`, `import`, `init` - **Étape suivante** : Pass a supported --format value; the command's --help lists them. ### INVALID_LOCALE [#invalid_locale] `pseudo --locale` n'est pas une étiquette de langue composée de lettres, de chiffres et de tirets, ou une locale saisie à une question interactive d'`init` n'est pas un code BCP 47 (les options `--source` et `--targets` échouent à la place avec `CONFIG_INVALID`). - **Levé par** : `pseudo`, `init` - **Étape suivante** : Give the locale as a language tag of letters, digits and hyphens, such as pt-BR or en-XA. ### INVALID_LOCALES [#invalid_locales] `--locales` a été donné mais ne liste aucune locale, ou les locales cibles saisies à une question interactive d'`init` incluent la locale source. - **Levé par** : `translate`, `watch`, `check`, `diff`, `export`, `tmx`, `report`, `init` - **Étape suivante** : Pass --locales as a comma-separated list of configured target locales, or omit it. ### INVALID_LOCK_TIMEOUT [#invalid_lock_timeout] `--lock-timeout` n'est pas un nombre entier de secondes de 1 à 3600. - **Levé par** : `translate`, `watch`, `import` - **Étape suivante** : Pass --lock-timeout as a whole number of seconds from 1 to 3600. ### INVALID_MAX_TOKENS [#invalid_max_tokens] `translate --max-tokens` n'est pas un nombre entier d'au moins 1. - **Levé par** : `translate` - **Étape suivante** : Pass --max-tokens as a whole number of at least 1. ### INVALID_OPTION [#invalid_option] Une option d'`init` ne correspond pas au fournisseur ou est mal formée : `--base-url` sans `openai-compatible` ni `libretranslate`, qui n'est pas une URL ou qui contient des identifiants, une query string ou un fragment ; `--api-key-env-var` avec un autre fournisseur qu'`openai-compatible`, ou qui n'est pas un nom de variable ; `--model` pour un fournisseur sans modèle (`deepl`, `google-translate`, `libretranslate`, `none`) ; une option quelconque avec une valeur vide ; `--targets` sans aucune locale ; `--path` sans `{locale}` ; `--client` sans `--agent`, sans client ou avec un client qu'init ne sait pas configurer. Ou bien `--cwd` ne nomme aucun répertoire existant (pour toute commande, avant son exécution), `doctor --data-flow` arrive avec `--literals`, `--locales` ou `--live`, `doctor --literals` arrive avec `--locales` ou `--live`, `check --file` ne nomme aucun fichier ou arrive avec `--locales`, `--consistency`, `--require-reviewed` ou `--sensitive`, ou `pseudo --mode` nomme un autre mode que `accented` ou `bidi`. - **Levé par** : toute commande qui accepte `--cwd`, ainsi que `init`, `doctor`, `check`, `pseudo` - **Étape suivante** : Correct or remove the flag the message names. ### INVALID_OUT [#invalid_out] `--out` sur `types` ou `pseudo` a été donné mais ne nomme aucun chemin. - **Levé par** : `types`, `pseudo` - **Étape suivante** : Pass --out with a file path, or omit it. ### INVALID_PORT [#invalid_port] `studio --port` n'est pas un entier de 1 à 65535. - **Levé par** : `studio` - **Étape suivante** : Pass --port as a whole number from 1 to 65535. ### INVALID_PROVIDER [#invalid_provider] `init --provider` ne nomme aucun fournisseur connu. - **Levé par** : `init` - **Étape suivante** : Pass --provider with a supported provider id; `verbatra init --help` lists them. ### INVALID_QA_OPTION [#invalid_qa_option] `check` a reçu `--severity` ou `--strict` sans `--qa` ni `--file`, ou `--strict` avec `--severity error`. - **Levé par** : `check` - **Étape suivante** : Add --qa or --file, and do not combine --strict with --severity error. ### INVALID_SEVERITY [#invalid_severity] `check --severity` n'est ni `error` ni `warning`. - **Levé par** : `check` - **Étape suivante** : Pass --severity error or --severity warning. ### LAYOUT_AMBIGUOUS [#layout_ambiguous] `init` a trouvé plusieurs motifs de fichiers qui conviennent aussi bien les uns que les autres ; `candidates` les liste. - **Levé par** : `init` - **Étape suivante** : Pass --path with one of the candidates. ### MISSING_OPTIONS [#missing_options] `init` n'a pas pu poser de question (pas de terminal, ou `--json`) et une valeur n'a été ni passée, ni détectée, ni fixée par défaut par `--yes` ; le message nomme chaque option manquante. - **Levé par** : `init` - **Étape suivante** : Pass the flags the message names, or --yes where the message offers it. ### REDACTION_UNSUPPORTED [#redaction_unsupported] `mcp --redact-values` a chargé un `@verbatra/mcp` plus ancien qui ne confirme pas masquer les valeurs ; le serveur a été arrêté avant de servir quoi que ce soit. - **Levé par** : `mcp` - **Étape suivante** : Upgrade @verbatra/mcp to the version that ships with this CLI, then start `verbatra mcp --redact-values` again. ### USAGE_ERROR [#usage_error] L'analyseur d'arguments a rejeté la ligne de commande (une option inconnue, un argument manquant), ou `mcp` a reçu des options qu'il ne peut pas accepter ; son `hint` nomme le `--help` de la commande. - **Levé par** : n'importe quelle commande - **Étape suivante** : Run the command with --help to see the options and arguments it accepts. ## Codes d'erreur du SDK [#sdk-error-codes] Les échecs de toute l'exécution lèvent une `SdkError` avec l'un de ces codes ; [Erreurs](https://verbatra.kreitz-webdev.de/fr/docs/sdk/errors.md) décrit la classe et quels codes portent une `cause`. Dans la CLI, un code levé termine l'exécution avec `2`, tandis qu'un code enregistré sur une locale en échec sort avec `1`. Là où l'index donne `2` ou `1`, `doctor` signale le code comme une vérification en échec et sort avec `1`. Les codes sans commande de la CLI te parviennent par le SDK, Studio ou le serveur MCP. ### CONFIG_NOT_FOUND [#config_not_found] Aucune config trouvée par la recherche, ou un `configPath` explicite n'existe pas (levé par `loadConfig`). - **Levé par** : toute commande qui charge la config - **Étape suivante** : Run `verbatra init` to create a config, or pass the path of an existing config file. ### CONFIG_INVALID [#config_invalid] Une config a été trouvée mais est impossible à analyser ou échoue à la validation, ou son fichier de glossaire n'a pas pu être résolu ; `translate` (en dry run aussi, sauf avec le fournisseur `none`) et `retranslateEntry` le lèvent aussi quand `VERBATRA_NETWORK_POLICY` ou `VERBATRA_NETWORK_ALLOWED_HOSTS` contient une valeur invalide, avant qu'aucun fournisseur ne soit construit. - **Levé par** : toute commande qui charge la config - **Étape suivante** : Fix the config field the message names, then run `verbatra doctor` to confirm the setup. ### UNKNOWN_FORMAT [#unknown_format] Aucun adaptateur n'est enregistré pour le format configuré ; levé avant toute lecture de fichier. - **Levé par** : toute commande qui lit des fichiers de locale ; Studio et le serveur MCP - **Étape suivante** : Set `format` in the config to a supported format, or register an adapter for this one. ### UNKNOWN_LOCALE [#unknown_locale] Une locale demandée n'est pas parmi les locales cibles configurées. - **Levé par** : `translate`, `watch`, `check`, `diff`, `export`, `tmx`, `report` ; Studio et le serveur MCP - **Étape suivante** : Use a locale from the config's `targetLocales`, or add it there first. ### UNKNOWN_KEY [#unknown_key] Une clé demandée n'est pas dans la ressource source (`keyValue`, `keyIntegrity`, `editEntry`, `retranslateEntry`, `approveEntry`, `rejectEntry`). - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Use a key that exists in the source locale file, or add it there first. ### KEY_PROTECTED [#key_protected] `retranslateEntry` a refusé de remplacer une valeur écrite, importée ou modifiée hors de verbatra par une personne, car ni `includeHuman` ni `humanEdits: "overwrite"` ne l'autorisaient. - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Keep the human-written value, or opt in to replacing it: include human edits for this call, or set `humanEdits: "overwrite"` in the config. ### KEY_PINNED [#key_pinned] La clé correspond aux `pinnedKeys` de la config, donc une écriture automatique a été refusée (`retranslateEntry`, et `editEntry` avec `actor: "agent"`). - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Edit the value by hand, or remove the key from `pinnedKeys` in the config to let verbatra write it. ### PROVIDER_CONSTRUCTION_FAILED [#provider_construction_failed] Le fournisseur n'a pas pu être construit ; enveloppe l'erreur du fournisseur lui-même, y compris une clé d'API manquante. Pour une clé manquante, l'indication nomme la variable au lieu de l'étape suivante ci-dessous, comme `Set GEMINI_API_KEY in the environment, or, with the CLI, in a .env file in the project directory.` Le SDK ne lit aucun fichier `.env`. - **Levé par** : `translate`, `watch` ; Studio et le serveur MCP - **Étape suivante** : Check the config's `provider` block and its API key environment variable, then run `verbatra doctor`. ### MACHINE_TRANSLATION_DISABLED [#machine_translation_disabled] La configuration fixe `provider: { id: "none" }`, donc une action dépensant auprès du fournisseur a été refusée avant qu'aucun fournisseur ne soit construit (`retranslateEntry`, `assertMachineTranslationEnabled`) ; `translate` et `watch` ne la lèvent jamais. - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Translate the key by hand, or configure a machine provider in place of `provider: { id: "none" }`. ### NETWORK_POLICY_VIOLATION [#network_policy_violation] La [politique réseau](https://verbatra.kreitz-webdev.de/fr/docs/network-policy.md) effective n'autorise pas le point de terminaison du fournisseur ni son proxy ; levée par `translate` hors exécution à blanc, par `watch` au démarrage et par `retranslateEntry`, avant de construire le fournisseur ou de lire une clé d'API. - **Levé par** : `translate`, `watch` ; Studio et le serveur MCP - **Étape suivante** : Point the provider at a host the network policy permits, or add its host to `network.allowedHosts` or VERBATRA_NETWORK_ALLOWED_HOSTS. ### SOURCE_UNREADABLE [#source_unreadable] Le fichier de la locale source n'existe pas, ou, pour `import` et `tmx import`, le fichier ou le répertoire à importer n'existe pas. - **Levé par** : toute commande qui lit des fichiers de locale ; Studio et le serveur MCP - **Étape suivante** : Create the source locale file, or fix `files.pattern` and `sourceLocale` in the config so they point at it. - **Étape suivante pour `import`** : Pass the path of the filled handoff file, or of the directory it was exported into, relative to the working directory or `--cwd`. - **Étape suivante pour `tmx import`** : Pass the path of an existing TMX file, relative to the working directory or `--cwd`. ### SOURCE_INVALID [#source_invalid] Le fichier de la locale source n'a pas pu être lu ou analysé ; enveloppe l'erreur de lecture de l'adaptateur. Pour `import` et `tmx import`, le fichier à importer est trop volumineux ou n'est pas un document d'échange ou TMX lisible. - **Levé par** : toute commande qui lit des fichiers de locale ; Studio et le serveur MCP - **Étape suivante** : Fix the file the message names so it parses under the configured format. - **Étape suivante pour `import`** : Fix the handoff file the message names, or pass its format with `--format` when its extension names none. - **Étape suivante pour `tmx import`** : Fix the TMX file the message names, or export it again from the tool that wrote it. ### LOCK_FILE_INVALID [#lock_file_invalid] Le fichier de verrouillage est présent mais corrompu, trop volumineux ou à une version non prise en charge. - **Levé par** : `translate`, `import`, `check`, `diff`, `export`, `report` ; Studio et le serveur MCP - **Étape suivante** : Restore verbatra.lock.json from version control, then try again. ### PROVENANCE_FILE_INVALID [#provenance_file_invalid] Le fichier de provenance est présent mais corrompu, trop volumineux ou mal formé ; levé par une écriture (`translate`, `watch`, `importWorkbook`, `editEntry`, `retranslateEntry`, `approveEntry`, `rejectEntry`) avant qu'elle ne change quoi que ce soit, et par `loadProvenance`, jamais par un rapport ; celui d'un verbatra plus récent est laissé intact à la place, et `translate`, `watch` et `importWorkbook` signalent l'avis `PROVENANCE_VERSION_UNRECOGNIZED`. - **Levé par** : `translate`, `watch`, `import` ; Studio et le serveur MCP - **Étape suivante** : Restore verbatra.provenance.json from version control, then try again. ### PROVENANCE_FILE_UNWRITABLE [#provenance_file_unwritable] Une décision de relecture n'a pas pu être enregistrée parce que le fichier de provenance vient d'un verbatra plus récent ou grossirait au-delà de la taille que verbatra relit (`approveEntry`, `rejectEntry`, `approveLocale`) ; rien n'est écrit. - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Upgrade verbatra if a newer version wrote verbatra.provenance.json, then record the decision again. ### REVIEW_VALUE_CHANGED [#review_value_changed] La clé n'a pas de valeur, ou sa valeur n'est pas l'`expectedValue` que la personne a vue, ou `expectedValue` n'est pas une chaîne (`approveEntry`, `rejectEntry`). - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Reload the current value, review it again, and resend the decision. ### REVIEW_SOURCE_CHANGED [#review_source_changed] La source a changé depuis l'écriture de la valeur, qui ne peut donc pas être approuvée telle quelle (`approveEntry`). - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Edit or retranslate the key first, then review its new value. ### REVIEW_REJECT_UNSUPPORTED [#review_reject_unsupported] Le format garde la valeur d'une clé quand le fichier est écrit sans elle, comme XLIFF, ou le fichier de locale est trop volumineux pour en garder une copie à restaurer, donc `rejectEntry` a laissé le fichier tel quel. - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Edit the value instead of rejecting it. ### REVIEW_RESTORE_FAILED [#review_restore_failed] `rejectEntry` a échoué après avoir réécrit le fichier de locale, et la restauration du fichier de locale ou du fichier de provenance a échoué aussi ; le message nomme l'échec d'origine (aussi la `cause`) et les fichiers à récupérer depuis le contrôle de version. - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Restore the files the message names from version control. ### REVIEWER_INVALID [#reviewer_invalid] `reviewer` est vide, dépasse 64 caractères ou contient un caractère de contrôle (`approveEntry`, `rejectEntry`, `approveLocale`, `importWorkbook`). - **Levé par** : `import --reviewer` ; Studio et le serveur MCP - **Étape suivante** : Pass a reviewer name of 1 to 64 characters with no control characters. ### LOCK_CONTENDED [#lock_contended] Le verrou d'écriture d'une locale, ou le verrou du glossaire que prend `updateGlossaryTerm`, n'a pas pu être acquis avant l'expiration de son délai, ou un autre processus l'a repris avant une écriture qu'il protège, et rien n'a été écrit ; le message nomme le chemin du fichier de verrouillage. - **Levé par** : `translate`, `watch`, `import` ; Studio et le serveur MCP - **Étape suivante** : Wait for the other verbatra process to finish and try again, or remove the lock file the message names if no process holds it. ### GLOSSARY_NOT_FILE_BACKED [#glossary_not_file_backed] Le glossaire de la config est inline ou absent : il n'y a donc aucun fichier de glossaire à lire ou à réécrire (`readGlossaryFile`, `updateGlossaryTerm`). Sans aucun glossaire configuré, l'indice dit à la place : Create a glossary file, such as glossary.json holding `{}`, and set the config's `glossary` to its path, such as `"glossary.json"`. - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Move the glossary into its own file and set the config's `glossary` to that file's path. ### GLOSSARY_UNWRITABLE [#glossary_unwritable] Le fichier de glossaire n'a pas pu être écrit, ou le verrou d'écriture du glossaire n'a pas pu être créé, par exemple dans un projet en lecture seule, ou libéré après une modification enregistrée (`updateGlossaryTerm`) ; l'erreur du système de fichiers est la `cause`. - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Make the glossary file and its directory writable, then try again. ### LOCALE_LAYOUT_INVALID [#locale_layout_invalid] `files.pattern` et `files.localeStyle` ne peuvent pas être combinés, ou le style n'a pas d'écriture de chemin valide pour une locale configurée. - **Levé par** : toute commande qui lit des fichiers de locale ; Studio et le serveur MCP - **Étape suivante** : Fix `files.pattern` and `files.localeStyle` in the config so every locale maps to a valid path. ### LOCALE_PATH_COLLISION [#locale_path_collision] Deux locales configurées résolvent vers le même chemin absolu. - **Levé par** : toute commande qui lit des fichiers de locale ; Studio et le serveur MCP - **Étape suivante** : Change `files.pattern` or `files.localeStyle` in the config so each locale resolves to its own file. ### CONCURRENCY_INVALID [#concurrency_invalid] `concurrency` a été défini mais n'est pas un entier d'au moins 1 ; levé avant l'exécution de toute locale. - **Levé par** : le SDK uniquement - **Étape suivante** : Pass a concurrency that is a whole number of at least 1. ### CONCURRENCY_BUDGET_CONFLICT [#concurrency_budget_conflict] Une exécution réelle a défini `concurrency` au-dessus de 1 alors qu'un budget de tokens s'applique, configuré ou propre à l'exécution ; levé avant tout appel au fournisseur (un dry run est exempté). - **Levé par** : `translate`, `watch` - **Étape suivante** : Run with a concurrency of 1 while a token budget applies, or remove the budget. ### MAX_TOKENS_INVALID [#max_tokens_invalid] Le `maxTokens` par exécution de `translate` a été fixé mais n'est pas un nombre entier d'au moins 1 ; levé avant toute lecture ou dépense. - **Levé par** : le SDK uniquement - **Étape suivante** : Pass a token budget that is a whole number of at least 1. ### LOCK_TIMEOUT_INVALID [#lock_timeout_invalid] `lockAcquireTimeoutMs` a été fixé mais n'est pas un nombre entier de millisecondes d'au moins 0 (`translate`, `watch` au démarrage, `importWorkbook`, `retranslateEntry`, `retranslateEntries`, `approveEntry`, `rejectEntry`, `approveEntries`, `rejectEntries`) ; levé avant toute lecture ou tout verrouillage. - **Levé par** : le SDK uniquement - **Étape suivante** : Pass a lock timeout that is a whole number of at least 0. ### PAGE_CURSOR_INVALID [#page_cursor_invalid] Le `cursor` passé à `localeValuesPage` ou `provenanceReportPage` est mal formé, dépasse `PAGE_CURSOR_MAX_LENGTH` (512), a été créé avec d'autres filtres ou pointe vers une clé déplacée ou disparue parce que les fichiers ont changé entre deux pages. - **Levé par** : le SDK ; l'outil d'agent `verbatra_locale_values` de Studio (`locale.values` et `report.provenance` du serveur MCP le signalent comme entrée invalide pour `cursor`) - **Étape suivante** : Call again without a cursor to start from the first page. ### PAGE_LIMIT_INVALID [#page_limit_invalid] Le `limit` passé à `localeValuesPage` ou `provenanceReportPage` n'est pas un nombre entier de 1 à `PAGE_LIMIT_CAP` (1000). - **Levé par** : le SDK uniquement - **Étape suivante** : Pass a page limit that is a whole number from 1 to 1000. ### TARGET_UNWRITABLE [#target_unwritable] Un fichier de locale cible n'a pas pu être écrit (son répertoire n'est pas inscriptible, n'existe pas, est en lecture seule ou est plein) ; le message nomme le fichier cible et le code du système de fichiers, jamais le fichier temporaire interne qu'utilise l'écriture atomique. - **Levé par** : `translate`, `import`, `pseudo` ; Studio et le serveur MCP - **Étape suivante** : Make the target locale file and its directory writable, then try again. ### PSEUDO_OUTPUT_CONFLICT [#pseudo_output_conflict] `pseudolocalize` s'est vu demander une pseudo-locale qui nomme une locale configurée, ou un chemin de sortie qui écrirait sur un fichier de locale configuré ou hors de `cwd`, y compris une fois les liens symboliques résolus ; refusé avant toute lecture et toute écriture. - **Levé par** : `pseudo` - **Étape suivante** : Choose a pseudolocale and an output path inside the project that name no configured locale. ### SOURCE_UNWRITABLE [#source_unwritable] Le fichier de la locale source n'a pas pu être écrit (`extract` uniquement) ; `xliff` et `apple-xcstrings` l'atteignent quand aucun catalogue n'existe encore, car ni l'un ni l'autre n'est créé à partir de rien. - **Levé par** : `extract` - **Étape suivante** : Make the source locale file writable; for xliff and apple-xcstrings, create the catalog first. ### EXTRACT_NOT_CONFIGURED [#extract_not_configured] `extract` a été appelé avec une config qui ne porte aucun bloc `extract`. - **Levé par** : `extract` - **Étape suivante** : Add an `extract` block to the config naming the framework and source roots. ### EXTRACT_FS_UNSUPPORTED [#extract_fs_unsupported] `extract` a reçu un `deps.fs` qui n'implémente pas `readDirectory` : aucun fichier source ne peut donc être découvert. - **Levé par** : le SDK uniquement - **Étape suivante** : Pass a file system that implements `readDirectory`, or use the default one. ### TYPES_OUTPUT_CONFLICT [#types_output_conflict] `generateTypes` a refusé son chemin de sortie : un chemin qui ne nomme aucun fichier (ou se termine par un séparateur de chemin), est absolu, sort de `cwd` avec `..` ou nomme `cwd` lui-même ou ne se termine pas par `.ts`, `.mts` ou `.cts`, et un chemin nommant un fichier de locale configuré, le fichier de verrouillage, le fichier de provenance, le cache de mémoire de traduction, un fichier que verbatra cherche pour sa configuration, le fichier de configuration chargé par l'exécution, ou le fichier de glossaire de la configuration, y compris une fois les liens symboliques résolus ; une exécution qui génère refuse en plus de remplacer un fichier existant qui ne commence pas par la ligne d'en-tête de verbatra. - **Levé par** : `types` - **Étape suivante** : Choose a relative `.ts`, `.mts` or `.cts` output path inside the project that names no file verbatra manages. ### TYPES_UNWRITABLE [#types_unwritable] Le fichier de déclarations que produit `generateTypes` n'a pas pu être écrit (son répertoire n'est pas inscriptible, n'existe pas, ou le disque est plein) ; le message nomme le fichier et le code du système de fichiers. - **Levé par** : `types` - **Étape suivante** : Make the output file and its directory writable, then try again. ### TMX_OUTPUT_CONFLICT [#tmx_output_conflict] `exportTmx` a refusé son chemin de sortie : un chemin qui ne nomme aucun fichier (ou se termine par un séparateur de chemin) ou qui tombe hors de `cwd` ou sur `cwd` lui-même, et un chemin nommant un fichier que verbatra gère, tels que les liste [`TYPES_OUTPUT_CONFLICT`](#types_output_conflict), y compris une fois les liens symboliques résolus ; refusé avant toute lecture de la mémoire. - **Levé par** : `tmx export` - **Étape suivante** : Choose an output path inside the project that names no locale file or other file verbatra manages. ### TMX_UNWRITABLE [#tmx_unwritable] Le fichier TMX que produit `exportTmx` n'a pas pu être écrit (son répertoire n'est pas inscriptible, un répertoire occupe déjà ce chemin, ou le disque est plein) ; le message nomme le fichier et le code du système de fichiers. - **Levé par** : `tmx export` - **Étape suivante** : Make the output file and its directory writable, then try again. ### MEMORY_UNWRITABLE [#memory_unwritable] `importTmx` n'a pas pu écrire le cache de mémoire de traduction `verbatra.cache.json` (son répertoire n'est pas accessible en écriture, un répertoire occupe déjà ce chemin, ou le disque est plein) ; le message nomme le fichier et le code du système de fichiers. - **Levé par** : `tmx import` - **Étape suivante** : Make verbatra.cache.json and its directory writable, then try again. ### EXPORT_OUTPUT_CONFLICT [#export_output_conflict] `exportWorkbook` a refusé son chemin de sortie : un chemin qui tombe hors de `cwd`, et un chemin qui, lui-même ou par un fichier que l'export écrirait dedans, nomme un fichier que verbatra gère, tels que les liste [`TYPES_OUTPUT_CONFLICT`](#types_output_conflict), y compris une fois les liens symboliques résolus ; un chemin `xlsx` qui ne nomme aucun fichier ou nomme `cwd` lui-même est aussi refusé ; refusé avant toute lecture. - **Levé par** : `export` - **Étape suivante** : Choose an output path inside the project that names no locale file or other file verbatra manages. ### EXPORT_UNWRITABLE [#export_unwritable] Le livrable que produit `exportWorkbook` n'a pas pu être écrit (son répertoire n'est pas inscriptible, un répertoire ou un fichier gêne, ou le disque est plein) ; le message nomme le fichier et le code du système de fichiers, et l'erreur du système de fichiers est la `cause`. - **Levé par** : `export` - **Étape suivante** : Make the output file and its directory writable, then try again. ### LOCALE_STATE_NOT_CARRIED_OVER [#locale_state_not_carried_over] Levé par `editEntry`, `retranslateEntry`, `approveEntry` et `rejectEntry`, qui n'écrivent alors rien ; sinon enregistré sur l'`error` d'une locale que `translate`, `watch` ou `importWorkbook` n'a pas exécutée parce que son état sous un code réécrit comme `pt_BR` n'a pas pu lui être déplacé dans le fichier de verrou ou le fichier de provenance ; l'exécution suivante réessaie ([Un code de locale réécrit](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md#un-code-de-locale-réécrit)). - **Levé par** : `translate`, `watch`, `import` ; Studio et le serveur MCP - **Étape suivante** : Wait for other verbatra processes to finish, make verbatra.lock.json and verbatra.provenance.json writable, then try again. ### LOCALE_UNSUPPORTED_BY_PROVIDER [#locale_unsupported_by_provider] Le fournisseur DeepL ou Google Cloud Translation configuré ne liste pas la locale source ou une locale cible sélectionnée dans la table de langues que verbatra embarque ; levé par `translate` (y compris une exécution à blanc et une estimation), `watch` au démarrage et `retranslateEntry`, avant qu'aucun fournisseur ne soit construit, aucune clé lue ou aucune locale démarrée ; une locale associée explicitement dans `localeMap` est considérée comme fiable à la place ([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)). - **Levé par** : `translate`, `watch` ; Studio et le serveur MCP - **Étape suivante** : Remove the unsupported locale from `targetLocales`, map it to a supported code in `provider.options.localeMap`, or choose a provider that supports it. ### NOT_A_LOCALE_FILE [#not_a_locale_file] `checkFile` a reçu un chemin qui n'est le fichier d'aucune locale configurée, ou aucun fichier n'existe à cet endroit. - **Levé par** : `check --file` - **Étape suivante** : Pass the path of an existing locale file that `files.pattern` maps to a configured locale. ### SENSITIVE_CONTENT_WITHHELD [#sensitive_content_withheld] `retranslateEntry` n'a pas envoyé la clé, ou a écarté sa réponse, parce que `sensitiveData.mode` vaut `block` ou `redact` et que la clé contient un contenu trouvé par un détecteur ou un motif qui n'a pas pu être envoyé ou n'est pas revenu intact ([Protection des contenus sensibles](https://verbatra.kreitz-webdev.de/fr/docs/data-handling.md#protection-des-contenus-sensibles)). `translate` et `watch` listent ces clés dans `sensitiveWithheld` à la place. - **Levé par** : Studio et le serveur MCP - **Étape suivante** : Remove the content from the key, list it in `sensitiveData.allow`, or turn the detector off in `sensitiveData.detectors`. ### RUN_CANCELLED [#run_cancelled] Le `signal` passé à `translate` ou `retranslateEntry` a été interrompu. `retranslateEntry` la lève quand l'interruption arrive avant la réponse du fournisseur, sans avoir rien écrit. `translate` l'enregistre sur chaque locale que l'annulation a empêchée de démarrer et marque le résumé comme [`cancelled`](https://verbatra.kreitz-webdev.de/fr/docs/sdk/run-summary.md). Un point d'entrée qui prend un verrou d'écriture, comme `editEntry`, `approveEntry` ou `updateGlossaryTerm`, la lève aussi quand `releaseHeldLocks` s'exécute au moment où il va prendre le verrou. - **Levé par** : le SDK uniquement - **Étape suivante** : Run the operation again to finish the work the cancellation left pending. ### LOCALE_FAILED [#locale_failed] Jamais levé : le `code` de repli enregistré sur l'`error` d'une locale échouée. - **Levé par** : `translate`, `watch`, `import` - **Étape suivante** : Fix the cause the locale's message names, then try again. ## Codes d'erreur des fournisseurs [#provider-error-codes] Un échec de fournisseur lève une `ProviderError` avec l'un de ces codes ([Erreurs structurées](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#erreurs-structurées)). Dans `translate` et `watch`, seule sa propre requête échoue : ses clés sont retenues, la locale reçoit un avis `SUB_BATCH_FAILED` qui nomme le code, et les clés sont reprises à la prochaine exécution. Une retraduction d'une seule clé depuis Studio ou le serveur MCP relève la `ProviderError`. Une requête en échec sort avec `1`, et sa locale finit `partial` ou `failed`. ### MISSING_API_KEY [#missing_api_key] La variable d'environnement requise est absente ou vide. Le message nomme la variable, jamais une valeur, et dans la CLI il arrive comme `causeCode` de `PROVIDER_CONSTRUCTION_FAILED`, avec la sortie `2`. Pour LibreTranslate, dont la clé est facultative, cela veut dire que le serveur a exigé une clé et que `LIBRETRANSLATE_API_KEY` n'est pas définie. - **Étape suivante** : Set the API key environment variable your provider reads, then run `verbatra doctor`. ### INVALID_REQUEST [#invalid_request] La requête a échoué à la validation avant tout appel réseau : un champ malformé, un code que DeepL n'accepte pas (une entrée de `localeMap` donnant un code source régional, ou une cible qui aboutit à un `en` ou `pt` nu), ou un code qui n'est pas du BCP-47 bien formé pour Google Cloud Translation. Pour LibreTranslate, cela couvre aussi une langue pour laquelle ton serveur n'a pas de modèle et une requête qui dépasse son `--char-limit` ou son `--batch-limit`. Réessayer n'aidera pas. - **Étape suivante** : Check the provider options in the config, such as the model name. ### INVALID_RESPONSE [#invalid_response] La sortie était malformée, incomplète, ou a échoué à la réconciliation avec la requête. - **Étape suivante** : Try again; if it keeps failing, configure a different model. ### OUTPUT_TRUNCATED [#output_truncated] Le modèle a atteint sa limite de tokens de sortie ; voir [Limites de tokens de sortie](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#limites-de-tokens-de-sortie). - **Étape suivante** : Translate fewer keys at a time, or configure a model with a larger output limit. ### PROVIDER_REFUSED [#provider_refused] Le modèle a refusé de répondre. - **Étape suivante** : Review the source text the provider refused, or translate it by hand. ### PROVIDER_BLOCKED [#provider_blocked] La requête ou la réponse a été bloquée ou filtrée pour raison de sécurité. - **Étape suivante** : Review the source text the provider blocked, or translate it by hand. ### RATE_LIMITED [#rate_limited] HTTP 429 ou une erreur de limite de débit du SDK. Pour Google Cloud Translation, cela couvre aussi un HTTP 403 dont le corps nomme un motif de quota (une limite quotidienne ou par minute). Google réutilise le 403 à la fois pour les échecs de quota et d'identifiants, donc augmente le quota Cloud Translation de ton projet. LibreTranslate signale aussi avec ce code un HTTP 403 dont le texte d'erreur dit "too many", car son serveur répond 403 à un client banni. - **Étape suivante** : Wait a moment and try again, or lower the concurrency. ### TIMEOUT [#timeout] Un délai réseau ou de requête dépassé ; [`requestTimeoutMs`](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#délai-de-requête) relève la borne. - **Étape suivante** : Try again, or raise the provider's `requestTimeoutMs` in the config. ### AUTH_FAILED [#auth_failed] HTTP 401 ou 403 : la clé est invalide, révoquée ou sans permission. Avec les fournisseurs Anthropic, OpenAI, Gemini, OpenCode et `openai-compatible`, le message nomme le statut et, sur un 403, ajoute que le serveur a refusé la requête selon sa politique ou les permissions de la clé. Pour Google Cloud Translation, vérifie que `GOOGLE_TRANSLATE_API_KEY` est une clé valide et sans restriction pour un projet où l'API Cloud Translation est activée. LibreTranslate signale aussi avec ce code un HTTP 400 dont le texte d'erreur mentionne une clé d'API lorsqu'une clé est configurée. Réessayer n'aidera pas. - **Étape suivante** : Check that the provider's API key is valid and allowed to use the configured model. ### PROVIDER_UNAVAILABLE [#provider_unavailable] HTTP 5xx : le fournisseur a échoué de son côté, et la requête elle-même n'a jamais été en cause. Là où un fournisseur [réessaie](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#nouvelles-tentatives), un 5xx transitoire est absorbé, donc un 5xx qui atteint ce code est une panne durable. Google Cloud Translation et LibreTranslate ne réessaient pas : un seul 5xx arrive donc ici aussitôt. - **Étape suivante** : Try again later, or check the configured endpoint. ### NETWORK_POLICY_VIOLATION [#provider-network_policy_violation] La [politique réseau](https://verbatra.kreitz-webdev.de/fr/docs/network-policy.md) a refusé la requête juste avant son envoi : le nom d'hôte pointait vers une adresse que la politique n'autorise pas, ou une réponse redirigeait vers un hôte refusé. Le message ne nomme que l'hôte. Réessayer n'aidera pas. - **Étape suivante** : Point the provider at a host the network policy permits, or add its host to `network.allowedHosts` or VERBATRA_NETWORK_ALLOWED_HOSTS. ### PROVIDER_ERROR [#provider_error] Tout ce qui est inclassable. Avec les fournisseurs Anthropic, OpenAI, Gemini, OpenCode et `openai-compatible`, un échec HTTP nomme son statut, par exemple `HTTP 404`, et le type d'erreur du serveur quand c'est un jeton court de lettres, chiffres et tirets bas, par exemple `MissingSessionID` ; le message propre du serveur, le corps de la réponse et le chemin de l'URL n'apparaissent jamais. Pour une `baseUrl` `openai-compatible`, un 404 ou 405 ajoute de vérifier que `baseUrl` est la racine de l'API, et un 400 ou 422 de vérifier le nom du modèle et la prise en charge de Chat Completions avec une sortie en JSON schema strict ; réessayer n'aidera pas pour un statut 4xx. Quand l'échec est un problème de transport reconnaissable, le message le nomme (connexion refusée, nom d'hôte non résolu, connexion fermée, hôte injoignable, certificat TLS non vérifié) et dit quoi vérifier ; sinon il se replie sur un message statique sans secret. Si un paquet de fournisseur n'a pas pu être chargé, le message nomme le paquet et te demande de réinstaller `@verbatra/sdk`. - **Étape suivante** : Act on the cause or HTTP status the message names, then check the provider's `baseUrl` (if it takes one), `model` and the rest of the `provider` block in the config. ## Codes d'erreur des adaptateurs de format [#adapter-error-codes] Un adaptateur de format qui ne peut pas traiter un fichier lève une `AdapterError` avec l'un de ces codes. Sur le fichier de locale source, elle arrive enveloppée dans `SOURCE_INVALID`, avec le code de l'adaptateur comme `causeCode` ; sur un fichier cible, elle devient l'`error.code` de cette locale. Toute commande qui lit des fichiers de locale, Studio et le serveur MCP peuvent la lever ; la CLI sort avec `2` quand le fichier source est en cause et avec `1` quand un fichier cible fait échouer sa locale dans `translate` ou `import`. `check --file` signale plutôt un fichier qui ne se parse pas comme un constat `syntax`. L'ensemble est fermé : un [adaptateur personnalisé](https://verbatra.kreitz-webdev.de/fr/docs/custom-format-adapters.md) lève l'un de ces codes plutôt que le sien. ### INVALID_JSON [#invalid_json] Un fichier de locale basé sur JSON n'est pas du JSON valide. Le message se termine par la ligne et la colonne quand le parser les indique. - **Étape suivante** : Fix the syntax error the message names in that file. ### INVALID_YAML [#invalid_yaml] Un fichier de locale YAML n'est pas du YAML valide. Le message se termine par la ligne et la colonne quand le parser les indique. - **Étape suivante** : Fix the syntax error the message names in that file. ### INVALID_XML [#invalid_xml] Un fichier de locale basé sur XML, comme XLIFF ou `strings.xml` d'Android, n'est pas du XML bien formé. - **Étape suivante** : Fix the syntax error the message names in that file. ### INVALID_STRUCTURE [#invalid_structure] Le fichier se parse, mais n'a pas la forme qu'attend le format configuré, par exemple une clé à points et un chemin de clés imbriqué qui mènent à la même clé, ou une clé de mapping YAML qui est une map ou une séquence. - **Étape suivante** : Reshape the file the message names to match the configured format. ### MAX_DEPTH_EXCEEDED [#max_depth_exceeded] Le fichier est imbriqué plus profondément que ce que verbatra lit. - **Étape suivante** : Reduce the nesting depth of the file the message names. ### INPUT_TOO_LARGE [#input_too_large] Le fichier est plus volumineux que ce que verbatra lit. - **Étape suivante** : Split the file the message names into smaller files. ### MIXED_STRUCTURE [#mixed_structure] Le fichier mélange des clés plates et imbriquées là où le format l'interdit. - **Étape suivante** : Use either flat or nested keys throughout the file the message names. ### ADAPTER_FAILED [#adapter_failed] Un adaptateur `custom:` a levé une erreur inattendue. L'erreur nomme le format de l'adaptateur, et l'erreur d'origine de l'adaptateur est sa `cause`. - **Levé par** : le SDK, avec un adaptateur `custom:` (la CLI ne charge aucun plugin) - **Étape suivante** : Report the failure to the maintainer of the custom adapter the message names. ### DUPLICATE_FORMAT [#duplicate_format] Un second adaptateur a été enregistré pour un identifiant de format que le registre contient déjà. - **Levé par** : `AdapterRegistry.register` dans le SDK - **Étape suivante** : Register only one adapter for each format identifier. ### INVALID_FORMAT_ID [#invalid_format_id] Un adaptateur a été enregistré sous un identifiant `custom:` mal formé. - **Levé par** : `AdapterRegistry.register` dans le SDK - **Étape suivante** : Name the custom adapter `custom:` followed by a valid name. ## Codes de la barrière de relecture [#check-result-codes] `check --require-reviewed` indique pourquoi il échoue dans `result.review.code` ([Exiger des traductions relues](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#exiger-des-traductions-relues)). ### REVIEW_REQUIRED [#review_required] Au moins une traduction écrite par la machine (origine `machine`, `memory`, `fuzzy` ou `agent`) n'est pas approuvée dans le `verbatra.provenance.json` commité. L'enveloppe reste `ok: true`, et `result.locales[].review.unreviewed` nomme les clés. - **Levé par** : `check --require-reviewed` - **Code de sortie** : `1` - **Étape suivante** : Approuve ou corrige les clés listées dans la [file de relecture de Studio](https://verbatra.kreitz-webdev.de/fr/docs/review-in-studio.md) ou avec les outils MCP `review.approve` et `review.reject`, puis commite `verbatra.provenance.json`. ### REVIEW_STATE_UNREADABLE [#review_state_unreadable] `verbatra.provenance.json` est corrompu ou vient d'un verbatra plus récent, donc aucun état de relecture ne peut être lu et la barrière échoue par sécurité. - **Levé par** : `check --require-reviewed` - **Code de sortie** : `1` - **Étape suivante** : Restaure `verbatra.provenance.json` depuis le contrôle de version, ou mets à jour verbatra si une version plus récente l'a écrit. ## Motifs de refus d'intégrité [#integrity-refusal-reasons] La [barrière d'intégrité](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md#la-barrière-dintégrité) refuse une valeur candidate avec exactement un de ces motifs, le premier qui s'applique dans l'ordre donné sur cette page. Le motif apparaît dans les `integrityRefusals` d'une locale après `translate`, `watch` et `import` (`integrity-withheld` dans la sortie lisible), dans le résultat de `editEntry` et de `retranslateEntry` (`accepted: false` avec le `reason`) et comme erreur de `check --qa`, souvent avec des `details` qui nomment ce qui diffère. Un refus sort avec `1` de `check --qa`, et de `translate` et `import` quand la locale finit partial ou failed. L'ensemble est publié sous la forme du tuple `INTEGRITY_GATE_REASONS`. ### placeholder [#placeholder] Les placeholders de la candidate diffèrent de ceux de sa source, comparés comme un multiensemble : le nombre compte, l'ordre non. Ce qui compte comme placeholder est défini par chaque [format](https://verbatra.kreitz-webdev.de/fr/docs/formats.md). Pour i18next, ngx-translate et YAML, un jeton de forme `{name}` que la candidate ajoute et que la source n'avait jamais est refusé aussi, même si les accolades simples y sont du texte littéral. Les détails nomment chaque placeholder supprimé avec `-` et chaque placeholder ajouté avec `+`, par exemple `-{{name}}` ou `+{{nom}}`. - **Étape suivante** : Remets les placeholders de la source dans la traduction, ou laisse l'exécution suivante la traduire à nouveau. ### markup [#markup] Le balisage HTML ou XML en ligne de la candidate diffère de celui de sa source, ou n'est pas bien formé. Les détails nomment chaque balise à l'origine du refus, précédée de `-` pour une balise que la source avait et que la candidate a supprimée, ou de `+` pour une balise que la candidate a inventée. - **Étape suivante** : Garde dans la traduction les balises, les noms d'attribut et les valeurs d'attribut protégées de la source. #### Comment le balisage est comparé [#comment-le-balisage-est-comparé] Les balises sont comparées comme un multiensemble de noms de balise plus noms d'attribut : - Refusé : une balise perdue, une balise inventée, une balise renommée, un ensemble de noms d'attribut différent (y compris l'ajout d'un attribut `dir` pour une cible écrite de droite à gauche), un balisage qui revient déséquilibré ou mal imbriqué, comme `ab`, et une balise qui revient imbriquée dans une autre du même nom alors que la source les avait côte à côte, ce qui transforme silencieusement deux liens en un seul. - Accepté : les mêmes balises dans un autre ordre, une valeur d'attribut différente, comme un `title` traduit ou un `href` localisé (dans les limites décrites plus bas pour les valeurs d'attribut), et l'une ou l'autre graphie d'un élément vide, `
` et `
` étant la même balise. - Comptées, pas seulement remarquées : la fusion de deux paires adjacentes en une seule (`a b` devenant `a b`) est refusée. - Comparées exactement : un changement de casse est un constat. Les éléments vides HTML (`
`, ``, `
` et les autres) n'ont besoin d'aucune balise fermante, quelle que soit leur casse, donc `
` est reconnu comme élément vide au même titre que `
`. Une source sans aucun balisage reste protégée contre le balisage qu'on y invente. La candidate est refusée pour toute paire de balises, tout élément vide ou toute balise auto-fermante qu'elle ajoute, pour une balise fermante sans balise ouvrante (`Hallo`) et pour une balise ouvrante jamais fermée qui porte autre chose que son nom, comme `` ou ``. Un `` jamais fermé qui ne porte que son nom, et dont le nom ne contient que des lettres, des chiffres, des tirets et des tirets bas, est un mot entre chevrons, comme `` dans `Druecke `. Ces mots sont mis de côté des deux côtés avant que la source soit jugée, donc une source qui en porte un reste comparée : une candidate qui perd une paire `` à côté de ``, ou qui invente une paire `` est refusé pour le ``. Là où un analyseur peut lire ce contenu de deux façons, la candidate est refusée sauf si elle est la source inchangée, avec un détail comme `+` : un `script` dont le contenu ouvre `