--- title: "Fichier de configuration" description: "Chaque clé de configuration avec son type, son défaut et la version qui l'a ajoutée, plus l'emplacement du fichier et l'échec d'une mauvaise configuration." type: "reference" --- # Fichier de configuration Chaque clé de configuration avec son type, son défaut et la version qui l'a ajoutée, plus l'emplacement du fichier et l'échec d'une mauvaise configuration. verbatra lit un objet de configuration sans secret et le valide avant tout travail. Aucune clé d'API n'est jamais lue depuis ce fichier ([Fournisseurs](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#les-clés-viennent-de-lenvironnement)), donc la configuration peut être commitée sans risque. ## Une configuration minimale [#une-configuration-minimale] ```ts title="verbatra.config.ts" import { defineConfig } from "@verbatra/cli"; export default defineConfig({ // Locales and files: required sourceLocale: "en", targetLocales: ["de", "fr"], format: "i18next-json", files: { // {locale} is the only token pattern: "locales/{locale}.json", }, // Provider: required; the API key comes from the environment, never from here provider: { id: "gemini", options: { // example model id; use your provider's current one model: "gemini-2.5-flash", maxOutputTokens: 4096, }, }, // Optional groups, each off or at its default until you add it: // tone: "informal", // glossary: "glossary.json", // network: { policy: "local-only" }, // sensitiveData: { mode: "warn" }, // maxTokens: 200000, // budgetBehavior: "stop", }); ``` Voir [locales et fichiers](#locales-et-fichiers), [provider](#provider), [glossary](#glossary), [network](#network), [contenu sensible](https://verbatra.kreitz-webdev.de/fr/docs/data-handling.md#protection-des-contenus-sensibles), [budget](#maxtokens-et-budgetbehavior), [rates](#rates) et [extract](#extract). `defineConfig` ne fait que typer son argument : `options.model` propose les identifiants de modèle du fournisseur, mais à l'exécution toute chaîne non vide est acceptée. ## Chaque clé [#chaque-clé] Les clés inconnues sont rejetées à chaque niveau sauf `$schema` et les maps dont tu nommes les clés, comme `maxLength`, `rates.table`, `localeMap` et un `glossary` en ligne, donc une clé d'API ne peut pas se trouver dans la configuration. | Clé | Type | Défaut | Depuis | Rôle | | --- | --- | --- | --- | --- | | `$schema` | chaîne | aucun | 0.9.0 | Pointe un éditeur vers le [JSON Schema](#validation-dans-léditeur) ; ignoré à l'exécution. | | `sourceLocale` | code de locale | requis | 0.1.0 | La locale dans laquelle tes chaînes source sont écrites. | | `targetLocales` | tableau de codes de locale | requis | 0.1.0 | Au moins une ; jamais `sourceLocale`, jamais deux égales sans tenir compte de la casse. | | `format` | id de format | requis | 0.1.0 | Le [format](https://verbatra.kreitz-webdev.de/fr/docs/formats.md) de tes fichiers de locale, ou un id `custom:` pour un [adaptateur extérieur](https://verbatra.kreitz-webdev.de/fr/docs/custom-format-adapters.md). | | `files.pattern` | chaîne | requis | 0.1.0 | Le chemin de chaque fichier de locale, avec un jeton `{locale}`. | | `files.localeStyle` | `"literal"`, `"posix"`, `"android"` | `"literal"` | 0.7.0 | Comment `{locale}` est écrit dans le chemin. | | `provider.id` | id de fournisseur | requis | 0.1.0 | Le fournisseur de traduction, ou `none` pour aucune traduction automatique. | | `provider.options` | objet | requis, sauf pour `none` | 0.1.0 | Les [options propres](https://verbatra.kreitz-webdev.de/fr/docs/providers.md) au fournisseur. | | `glossary` | objet ou chemin de fichier | aucun | 0.1.0 | Traductions fixes, traductions interdites et termes à ne pas traduire. | | `tone` | `"formal"`, `"informal"`, `"neutral"` | aucun | 0.1.0 | Le registre des traductions, appliqué [selon le fournisseur](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#ton-et-glossaire-selon-les-fournisseurs). | | `prune` | booléen | `false` | 0.3.0 | Supprime les clés orphelines des fichiers cibles et du fichier de verrouillage ; `translate --prune` prime. | | `generatePlurals` | booléen | `false` | 0.3.0 | Synthétise les formes plurielles CLDR dont une langue cible a besoin. | | `fuzzyCache.enabled` | booléen | requis dans le bloc | 0.11.0 | Réutilise la traduction d'une source peu modifiée. | | `fuzzyCache.threshold` | nombre, de `0.5` à `1` | `0.9` | 0.11.0 | À quel point ancienne et nouvelle source doivent se ressembler. | | `humanEdits` | `"protect"`, `"suggest"`, `"overwrite"` | `"protect"` | 0.12.0 | Ce que fait une exécution d'une clé obsolète écrite par une personne. | | `pinnedKeys` | tableau de chaînes | aucun | 0.12.0 | Des motifs de clés (`*` en joker) qu'aucune écriture automatique ne touche. | | `network.policy` | `"any"`, `"local-only"`, `"allowlist"` | `"any"` | 0.12.0 | Les hôtes auxquels un fournisseur peut [se connecter](https://verbatra.kreitz-webdev.de/fr/docs/network-policy.md). | | `network.allowedHosts` | tableau de chaînes | aucun ; requis pour `"allowlist"` | 0.12.0 | Hôtes autorisés en plus : noms, jokers `*.suffix`, IP ou plages CIDR. | | `sensitiveData.mode` | `"off"`, `"warn"`, `"block"`, `"redact"` | obligatoire dans le bloc ; `"off"` sans le bloc | 0.12.0 | Ce qu'une exécution fait du [contenu sensible](https://verbatra.kreitz-webdev.de/fr/docs/data-handling.md#protection-des-contenus-sensibles) avant l'envoi. | | `sensitiveData.detectors` | tableau d'ID de détecteurs | `secret`, `email`, `iban`, `credit-card` | 0.12.0 | Détecteurs actifs ; `phone`, `ip`, `private-host` sont optionnels. | | `sensitiveData.patterns` | tableau de chaînes | aucun | 0.12.0 | Expressions régulières pour tes propres termes, comme des noms de code. | | `sensitiveData.allow` | tableau de chaînes | aucun | 0.12.0 | Correspondances jamais signalées ; `*` est un joker et la casse est ignorée. | | `maxBatchSize` | entier positif | `50` | 0.3.0 | Le maximum d'entrées par requête fournisseur. | | `maxLength` | table de clé vers entier positif | aucun | 0.11.0 | Longueurs maximales par clé, en groupes de graphèmes. | | `maxTokens` | entier positif | aucun | 0.5.0 | Un budget de tokens pour toute l'exécution. | | `budgetBehavior` | `"warn"`, `"stop"` | `"warn"` | 0.5.0 | Si atteindre `maxTokens` avertit ou arrête les envois. | | `rates.asOf` | date `YYYY-MM-DD` | requis dans le bloc | 0.11.0 | La date à laquelle tu as lu les tarifs. | | `rates.currency` | trois lettres majuscules | requis dans le bloc | 0.11.0 | La devise de chaque tarif, comme `USD`. | | `rates.table` | table de clé de tarif vers tarif | requis dans le bloc | 0.11.0 | Les tarifs par [clé de tarif](#rates). | | `extract.framework` | `"i18next"` | requis dans le bloc | 0.11.0 | Les appels que l'analyse du code source recherche. | | `extract.roots` | tableau de chaînes | requis dans le bloc | 0.11.0 | Les répertoires à analyser, au moins un. | | `extract.exclude` | tableau de chaînes | aucun | 0.11.0 | Des noms de répertoire supplémentaires à ignorer. | | `extract.literals.ignore` | tableau de chaînes | aucun | 0.11.0 | Des textes exacts que `doctor --literals` retient. | | `extract.unused.ignore` | tableau de chaînes | aucun | 0.11.0 | Des clés ou motifs `*` que `diff --unused` ne signale jamais. | ### Locales et fichiers [#locales-et-fichiers] - **`files.pattern`** doit contenir `{locale}`, son seul jeton, et se résout par rapport à la racine du projet : `locales/{locale}.json` devient `locales/de.json`. C'est un chemin littéral, jamais un glob, donc une configuration adresse un fichier par locale ([Dispositions avec espaces de noms](https://verbatra.kreitz-webdev.de/fr/docs/formats.md#dispositions-avec-espaces-de-noms)) ; `apple-xcstrings` résout chaque locale vers le même catalogue ([Xcode String Catalogs](https://verbatra.kreitz-webdev.de/fr/docs/formats.md#xcode-string-catalogs-xcstrings)). - **`files.localeStyle`** décide en quoi le jeton se développe : - `literal` écrit l'étiquette telle qu'elle est configurée, comme le veulent la plupart des dispositions. - `posix` remplace `-` par `_` pour gettext et la disposition Java `messages_{locale}.properties` (`pt-BR` devient `pt_BR`) ; une variante comme `de-1996` n'a pas d'écriture posix. `gettext-po` écrit les écritures à la manière de gettext (section suivante). - `android` se développe en un répertoire de ressources, écrit sous la forme `res/{locale}/strings.xml` : `values` pour la source, puis `values-de`, `values-pt-rBR`, `values-b+zh+Hans`. Un style refuse une locale qu'il ne sait pas écrire. ### Noms de locale gettext [#noms-de-locale-gettext] Avec `format: "gettext-po"` et `localeStyle: "posix"`, les fichiers portent des noms gettext (`language_REGION@modifier`) tandis que la configuration garde des codes BCP 47 : | Code dans la configuration | Nom de fichier | | --- | --- | | `pt-BR` | `pt_BR` | | `es-419` | `es_419` | | `sr-Latn` | `sr@latin` | | `sr-Latn-RS` | `sr_RS@latin` | | `uz-Cyrl` | `uz@cyrillic` | | `ks-Deva-IN` | `ks_IN@devanagari` | | `zh-Hant-TW` | `zh_TW` | | `sr-Cyrl-RS` | `sr_RS` | Une écriture que la langue et la région impliquent déjà est omise, donc `zh-TW` et `zh-Hant-TW` ensemble échouent avec `LOCALE_PATH_COLLISION` ; une écriture sans modificateur gettext, comme `zh-Hant` seul, échoue avec `LOCALE_LAYOUT_INVALID`. [`verbatra init`](https://verbatra.kreitz-webdev.de/fr/docs/cli/init.md) relit ces noms. Les autres formats gardent l'écriture ICU (`sr_Latn`). ### Codes de locale [#codes-de-locale] Chaque code de locale doit être une étiquette qu'accepte `Intl.getCanonicalLocales`, avec une sous-étiquette de langue de deux ou trois lettres, sinon le chargement échoue avec `CONFIG_INVALID` : `pt_BR` (écris `pt-BR` avec `localeStyle: "posix"`) et `german` sont rejetés. Un code valide non canonique, comme `zh-hant-tw` ou l'obsolète `iw`, fonctionne tel qu'il est écrit. ### provider [#provider] `provider.id` sélectionne l'un des [fournisseurs](https://verbatra.kreitz-webdev.de/fr/docs/providers.md) ou `none`, dont `options` peut être omis et doit sinon valoir `{}` ([Travailler sans traduction automatique](https://verbatra.kreitz-webdev.de/fr/docs/human-only-workflow.md)). Les autres fournisseurs acceptent `options.localeMap` et `options.requestTimeoutMs` ([Fournisseurs](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#codes-de-locale-envoyés-au-fournisseur)) ; depuis 0.12.0, une clé mal placée sous `provider`, comme `localeMap`, échoue avec `CONFIG_INVALID`. ### glossary [#glossary] Des termes traduits d'une façon fixe, en ligne ou comme chemin vers un fichier JSON de la même forme (jamais fusionnées). La version 1 associe chaque terme source à une traduction pour toutes les locales : ```ts title="verbatra.config.ts" export default defineConfig({ // ... glossary: { "Sign in": "Anmelden", }, // or: glossary: "glossary.json", }); ``` Un chemin relatif se résout par rapport au répertoire du fichier de configuration ; le fichier doit être en UTF-8, ne pas dépasser 1 MiB, et il est lu une fois au chargement. Un fichier absent, un JSON invalide ou une forme invalide échoue avec `CONFIG_INVALID`, en nommant le chemin et, pour la version 2, le champ. Mets un terme `__proto__` dans un fichier ; un littéral JavaScript le transforme en prototype. #### Glossaire par locale (version 2) [#glossaire-par-locale-version-2] La version 2 ajoute des traductions par locale, des traductions interdites et des termes à garder tels qu'ils sont écrits : ```json title="glossary.json" { "version": 2, "terms": [ { "source": "Dashboard", "targets": { "de": "Übersicht", "fr": "Tableau de bord" }, "forbidden": { "de": ["Instrumententafel"] }, "note": "The start page after sign-in", "partOfSpeech": "noun" }, { "source": "Sign in", "target": "Anmelden", "caseSensitive": true } ], "doNotTranslate": ["verbatra", { "term": "Acme", "caseSensitive": false }] } ``` | Champ | Signification | | --- | --- | | `version` | Toujours `2` ; tout autre nombre échoue. | | `terms[].source` | Le terme source ; chaque terme apparaît une seule fois. | | `terms[].target` | La traduction pour chaque locale sans entrée propre dans `targets`. | | `terms[].targets` | Les traductions par locale. Une locale prend sa propre entrée, puis celle de sa langue de base (`de` couvre `de-AT`), puis `target`, en comparant les codes canoniques sans tenir compte de la casse. | | `terms[].forbidden` | Les traductions qu'une locale ne doit jamais utiliser ; une locale régionale respecte aussi la liste de sa langue de base. | | `terms[].caseSensitive` | Comparer le terme, les traductions et les traductions interdites en tenant compte de la casse. `false` par défaut. | | `terms[].note`, `terms[].partOfSpeech` | Un contexte en texte libre, envoyé comme données à un fournisseur LLM. | | `doNotTranslate` | Les termes recopiés sans traduction. Une simple chaîne garde sa casse ; `{ "term", "caseSensitive": false }` peut la changer. | Chaque terme a besoin d'un `target`, d'une entrée dans `targets` ou d'une liste `forbidden` ; il ne peut pas interdire sa propre traduction, nommer deux fois une locale ni figurer dans `doNotTranslate`. Aucun texte ne peut être vide ; un terme compte au plus 200 caractères, une traduction ou une forme interdite 2000, une `note` 500 et une `partOfSpeech` 50. L'empreinte de [cache](https://verbatra.kreitz-webdev.de/fr/docs/the-cache.md) d'une locale ne couvre que ses propres termes. Un fichier version 1 garde son empreinte ; [`updateGlossaryTerm`](https://verbatra.kreitz-webdev.de/fr/docs/sdk/config.md#updateglossaryterm) ne le réécrit en version 2 que pour une modification que la version 1 ne sait pas exprimer. [Studio](https://verbatra.kreitz-webdev.de/fr/docs/review-in-studio.md) ne modifie que la forme fichier, un terme à la fois. Les fournisseurs qui appliquent le glossaire sont indiqués dans [Fournisseurs](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#ton-et-glossaire-selon-les-fournisseurs) ; chaque sortie est [vérifiée ensuite](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md). ### generatePlurals [#generateplurals] Quand il vaut true, verbatra synthétise les formes plurielles CLDR dont une cible a besoin mais que la source n'a pas, comme `few` et `many` pour le polonais, et les clés ordinales (`_ordinal_`) selon les règles ordinales CLDR. Seul `i18next-json` avec un fournisseur LLM le prend en charge ; tout le reste, et une locale sans règles CLDR, reçoit l'[avertissement de pluriel](https://verbatra.kreitz-webdev.de/fr/docs/language-support.md#pluriels) (les ordinaux supposent `other`). Il n'y a pas d'option CLI ; `translate()` du SDK accepte une surcharge par exécution. ### fuzzyCache [#fuzzycache] `fuzzyCache: { enabled: true }` laisse une source modifiée réutiliser la traduction de sa forme antérieure quand les deux se ressemblent au moins à hauteur de `threshold`, toujours signalée avec `FUZZY_CACHE_REUSE` ([Réutilisation approximative](https://verbatra.kreitz-webdev.de/fr/docs/the-cache.md#réutilisation-approximative)) ; `--no-cache` le contourne. ### humanEdits et pinnedKeys [#humanedits-et-pinnedkeys] `humanEdits` couvre une clé obsolète dont la valeur a été écrite par une personne ([provenance](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md#la-provenance-de-chaque-valeur) `human`, `import` ou `external`) ; une clé qui correspond à `pinnedKeys` (comme `["legal.*", "brand.name"]`) n'est jamais écrite par une machine, quoi que dise `humanEdits`. `*` correspond à toute suite de caractères, points compris, et la comparaison est sensible à la casse. Ce que fait chaque mode est décrit dans [Garder les traductions humaines](https://verbatra.kreitz-webdev.de/fr/docs/protecting-human-translations.md). ### network [#network] Voir [Restreindre l'accès réseau](https://verbatra.kreitz-webdev.de/fr/docs/network-policy.md). ```ts title="verbatra.config.ts" network: { policy: "local-only", allowedHosts: ["gpu.lan"] } ``` ### maxBatchSize [#maxbatchsize] Les entrées manquantes et modifiées partent en [sous-lots](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#découpage-en-lots) séquentiels d'au plus cette taille. Aucune option CLI ne le remplace. ### maxLength [#maxlength] Des limites de longueur par clé, pour les chaînes soumises à une contrainte de mise en page : ```ts title="verbatra.config.ts" maxLength: { "nav.dashboard": 18, "cta.submit": 12, } ``` - **Ici ou dans `verbatra.limits.json`.** Les clés sont comparées littéralement, jamais comme des globs ; une clé fixée dans aucun des deux n'est jamais mesurée. `setKeyLengthLimit` n'accepte que des clés de la source, donc Studio ne peut pas limiter une forme plurielle générée ; une entrée écrite à la main pour sa propre clé s'applique. Le fichier versionné à côté du fichier de verrou accepte `{ "version": 1, "maxLength": { ... } }`, la config l'emporte par clé et [`setKeyLengthLimit`](https://verbatra.kreitz-webdev.de/fr/docs/sdk/config.md#setkeylengthlimit) l'écrit. - **Groupes de graphèmes.** La longueur compte les caractères perçus, espaces compris : un emoji, une lettre accentuée ou un caractère CJK compte pour un. La limite est inclusive. - **Quand.** Chaque valeur que `translate` produit pour la clé, réutilisations du cache comprises ; une clé à jour n'est mesurée que quand sa source change, ou par [`export --include-unchanged`](https://verbatra.kreitz-webdev.de/fr/docs/cli/export.md). - **Consultatif.** Un dépassement est quand même écrit et verrouillé, et signalé pour relecture comme [`MAX_LENGTH_EXCEEDED`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#max_length_exceeded). ### maxTokens et budgetBehavior [#maxtokens-et-budgetbehavior] `maxTokens` est un budget pour toute l'exécution : tokens d'entrée plus de sortie sur chaque appel fournisseur (traduction et génération de pluriels) et chaque locale cible. [`translate --max-tokens`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md#plafond-de-tokens) peut le resserrer pour une exécution, jamais le relâcher, et toujours comme un `"stop"` ferme. `budgetBehavior` décide de ce qui se passe alors : - `"warn"`, la valeur par défaut, compte la dépense et signale le dépassement, mais continue. - `"stop"` en fait un plafond pour chaque fournisseur. Avant chaque requête, l'exécution projette son coût comme [l'estimation préalable](https://verbatra.kreitz-webdev.de/fr/docs/estimating-cost.md) et refuse une requête qui dépasserait `maxTokens`. Les clés de cette requête et chaque clé pas encore tentée (le reste de la locale et chaque locale suivante, dont la comparaison et le rapport d'orphelines tournent quand même) sont retenues, gardent leur hash de verrouillage précédent et sont retentées à l'exécution suivante. Sous `"stop"` : - Après chaque requête, le total est réconcilié avec l'usage remonté par le fournisseur : une exécution peut donc finir légèrement au-dessus de `maxTokens` ([le `budget` du résumé d'exécution](https://verbatra.kreitz-webdev.de/fr/docs/sdk/run-summary.md#anatomie-du-runsummary)). Les fournisseurs de traduction automatique ne remontent aucun token et sont budgétés à partir de la projection. - Une requête échouée ou tronquée est entièrement comptée. - La projection ajoute une allocation fixe pour le prompt LLM, aussi pour les fournisseurs de traduction automatique, et couvre un lot entier, donc un `maxTokens` inférieur à la projection d'un lot le refuse à chaque exécution ; l'avis dit de baisser `maxBatchSize` ou d'augmenter `maxTokens`. - Une locale dont des clés ont été retenues est `partial`, ou `failed` si aucune clé n'est arrivée, et les deux sortent avec `1`. Sous `"warn"`, le code de sortie ne change jamais. Le budget borne une exécution de `translate`, jamais la retraduction d'une seule entrée ; `watch` en démarre un neuf par exécution. Un budget exclut [`--concurrency`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md#locales-en-parallèle) supérieur à `1` sur une exécution réelle ; un dry run est exempté. `budgetBehavior` sans `maxTokens` n'a aucun effet. Le `maxTokens` de premier niveau est ce budget de toute l'exécution ; le `provider.options.maxTokens` d'Anthropic, sans lien avec lui, plafonne une réponse ([Fournisseurs](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#anthropic)). ### rates [#rates] Lu uniquement par [`translate --estimate`](https://verbatra.kreitz-webdev.de/fr/docs/estimating-cost.md), qui transforme les tarifs en argent ; une exécution réelle l'ignore. ```ts title="verbatra.config.ts" rates: { asOf: "2026-01-15", currency: "USD", table: { // placeholders: copy the current rates from each provider's pricing page "gemini/gemini-2.5-flash": { inputPerMillionTokens: 1, outputPerMillionTokens: 2 }, deepl: { perMillionCharacters: 1 }, }, } ``` Une clé de `table` est `provider/model`, ou l'id seul pour un fournisseur sans modèle (`deepl`, `google-translate`). Une entrée est facturée aux tokens (`inputPerMillionTokens`, `outputPerMillionTokens`) ou aux caractères (`perMillionCharacters`), jamais les deux, et un tarif négatif, un tarif au-delà de 1 000 000 000 par million ou la mauvaise unité est refusé. `openai-compatible` et `libretranslate` n'envoient aucune facture, donc leur quantité est indiquée sans tarif. ### extract [#extract] Lu uniquement par [`extract`](https://verbatra.kreitz-webdev.de/fr/docs/cli/extract.md), [`doctor --literals`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md#littéraux-non-traduits) et [`diff --unused`](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md#clés-source-inutilisées). ```ts title="verbatra.config.ts" extract: { framework: "i18next", roots: ["src", "app"], exclude: ["generated"], literals: { ignore: ["Acme Inc."] }, unused: { ignore: ["emails.*"] }, } ``` - **`framework`** doit en nommer un doté d'un extracteur ([formes d'appel](https://verbatra.kreitz-webdev.de/fr/docs/cli/extract.md#ce-quelle-trouve)) ; tout autre est refusé. - **`roots`** se résolvent par rapport à la racine du projet ; **`exclude`** ajoute des noms de répertoire (pas des chemins), reconnus n'importe où sous une racine, à l'[ensemble toujours ignoré](https://verbatra.kreitz-webdev.de/fr/docs/cli/extract.md#limites-de-lanalyse). - **`literals.ignore`** correspond au texte complet d'un littéral, espaces regroupés et références décodées ([Littéraux non traduits](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md#littéraux-non-traduits)). - **`unused.ignore`** est comparé à la clé décodée ([`diff --unused`](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md#clés-source-inutilisées)). ## Ordre de découverte [#ordre-de-découverte] verbatra cherche vers le haut depuis le répertoire de travail et prend la première correspondance, en s'arrêtant au répertoire le plus proche qui contient `.git`, sinon à ton répertoire personnel (ou au répertoire de travail quand le personnel n'est pas au-dessus), donc il ne prend jamais une configuration située au-dessus de ton dépôt : 1. `package.json` (une propriété `"verbatra"`) 2. `.verbatrarc` 3. `.verbatrarc.json` 4. `.verbatrarc.yaml` 5. `.verbatrarc.yml` 6. `.verbatrarc.js` 7. `.verbatrarc.cjs` 8. `.verbatrarc.ts` 9. `verbatra.config.js` 10. `verbatra.config.cjs` 11. `verbatra.config.ts` `--config ` charge un seul fichier à la place, relatif au répertoire de travail ; la priorité côté SDK est décrite sous [`loadConfig`](https://verbatra.kreitz-webdev.de/fr/docs/sdk/config.md#loadconfig). ## Validation dans l'éditeur [#validation-dans-léditeur] `@verbatra/sdk` livre un JSON Schema généré à partir de son schéma zod, servi aussi à une URL stable pour toute installation, `npx`, un monorepo avec hoisting ou un agent distant : ```text https://verbatra.kreitz-webdev.de/schema/v1/config.json ``` Hors ligne, ou pour figer la version installée, utilise la copie du paquet, `./node_modules/@verbatra/sdk/dist/config-schema.json` ([tous les schémas](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#schémas)). `.verbatrarc.json` et `.verbatrarc` prennent une clé `$schema` pour VS Code : ```json title=".verbatrarc.json" { "$schema": "https://verbatra.kreitz-webdev.de/schema/v1/config.json", "sourceLocale": "en", "targetLocales": ["de", "fr"], "format": "i18next-json", "files": { "pattern": "locales/{locale}.json" }, "provider": { "id": "gemini", "options": { "model": "gemini-2.5-flash", "maxOutputTokens": 4096 } } } ``` Le `.verbatrarc` sans extension a aussi besoin d'une association de fichiers dans l'espace de travail : ```json title=".vscode/settings.json" { "json.schemas": [ { "fileMatch": [".verbatrarc", ".verbatrarc.json"], "url": "https://verbatra.kreitz-webdev.de/schema/v1/config.json" } ] } ``` Une configuration YAML prend un commentaire YAML Language Server : ```yaml title=".verbatrarc.yaml" # yaml-language-server: $schema=https://verbatra.kreitz-webdev.de/schema/v1/config.json sourceLocale: en targetLocales: [de, fr] format: i18next-json files: pattern: "locales/{locale}.json" provider: id: gemini options: model: gemini-2.5-flash maxOutputTokens: 4096 ``` `package.json` ne prend pas de schéma ; les formes exécutables sont typées par `defineConfig`. ### Ce que le document ne peut pas vérifier [#ce-que-le-document-ne-peut-pas-vérifier] Seul le chargement de la configuration vérifie ces règles : les règles de `targetLocales` et des [codes de locale](#codes-de-locale), les clés de [`localeMap`](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#codes-de-locale-envoyés-au-fournisseur) et les règles de `baseUrl` et [`apiKeyEnvVar`](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#openai-compatible) d'`openai-compatible`, des adresses et plages valides dans [`network.allowedHosts`](https://verbatra.kreitz-webdev.de/fr/docs/network-policy.md), `sensitiveData.patterns` dans les [règles de sécurité des motifs](https://verbatra.kreitz-webdev.de/fr/docs/data-handling.md#protection-des-contenus-sensibles) et les règles des termes d'un glossaire en ligne en [version 2](#glossaire-par-locale-version-2). ## Le répertoire de travail et .env [#le-répertoire-de-travail-et-env] Le répertoire de travail (là où tu lances verbatra, ou `--cwd`) lance la recherche de configuration et contient les [fichiers d'environnement](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#fichiers-denvironnement). Les chemins de locale, `verbatra.lock.json`, le cache, le fichier de provenance et `.verbatra-local/` sont résolus par rapport à la racine du projet, le répertoire de la configuration trouvée, donc une exécution depuis un sous-répertoire utilise les mêmes fichiers. Avec `--config`, le répertoire de travail est la racine, et une configuration située ailleurs reçoit une note sur stderr, car le chemin de son glossaire est résolu par rapport à son propre répertoire. Un chemin que tu passes, comme `--out` ou `check --file`, est résolu par rapport au répertoire de travail. ## Quand le chargement échoue [#quand-le-chargement-échoue] - [`CONFIG_NOT_FOUND`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#config_not_found) : aucune configuration à aucun des endroits cherchés, ou le chemin `--config` n'existe pas. - [`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#config_invalid) : une configuration a été trouvée mais n'est pas utilisable. Le message liste chaque problème avec son chemin de clé ; une clé inconnue ajoute l'indice que les clés d'API viennent de l'environnement. Un échec d'analyse nomme le fichier (avec la ligne et la colonne pour YAML) mais ne cite jamais son contenu, et chaque message passe par la rédaction des clés. La CLI sort avec `2` dans les deux cas.