Fichier de configuration

verbatra lit un petit objet de configuration sans secret et le valide avant de faire le moindre travail. Cette page est la référence complète : chaque clé, où le fichier peut vivre, et comment une mauvaise configuration échoue.

Une configuration minimale

import { defineConfig } from "@verbatra/sdk";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de", "fr"],
  format: "i18next-json",
  files: {
    pattern: "locales/{locale}.json",
  },
  provider: {
    id: "gemini",
    options: {
      model: "gemini-2.5-flash", // example model id; use your provider's current one
      maxOutputTokens: 4096,
    },
  },
});

defineConfig est un assistant identité de @verbatra/sdk. Il renvoie son argument tel quel et n'existe que pour te donner l'inférence de types et l'autocomplétion de l'éditeur.

Chaque clé

Les clés de premier niveau inconnues sont rejetées. C'est aussi pourquoi une clé d'API ne peut pas vivre dans la configuration : les clés viennent de l'environnement, pas du fichier.

Locales et fichiers

• sourceLocale doit être une chaîne non vide.
• targetLocales doit contenir au moins une locale, ne doit pas inclure sourceLocale, et deux entrées ne peuvent pas être égales sans tenir compte de la casse (par exemple ["de", "DE"] est rejeté), puisque chaque locale devient le nom de sa propre feuille Excel à l'export.
• format est l'un de i18next-json, vue-i18n-json, next-intl-json, ngx-translate-json, xliff, yaml, arb ou properties. Voir Formats.
• files.pattern doit contenir le jeton {locale}, que verbatra remplace par chaque locale : locales/{locale}.json se résout en locales/de.json. Les chemins se résolvent contre le répertoire de travail.

provider

Un objet sélectionné par id : anthropic, openai, gemini, deepl ou openai-compatible. Chaque fournisseur prend ses propres options (modèle, limite de tokens, et champs spécifiques au fournisseur), et les clés d'option inconnues sont rejetées. Les options par fournisseur sont documentées sur Fournisseurs.

glossary

Une correspondance de termes source vers des termes cibles préférés, soit en ligne, soit comme chemin vers un fichier JSON de la même forme (un objet plat de clés chaînes vers valeurs chaînes) :

export default defineConfig({
  // ...
  glossary: {
    "Sign in": "Anmelden",
  },
  // or: glossary: "glossary.json",
});

Les deux formes sont mutuellement exclusives ; il n'y a pas de fusion entre elles. Un chemin de fichier relatif se résout contre le répertoire du fichier de configuration chargé, ou contre le répertoire de travail quand la configuration est passée comme surcharge en mémoire. Le fichier doit être encodé en UTF-8 et ne pas dépasser 1 MiB, et il est lu une fois au chargement de la configuration : verbatra ne le surveille pas, donc modifie-le et redémarre pour prendre en compte une mise à jour. Un fichier absent, un JSON invalide ou une valeur qui n'est pas une carte plate de chaînes fait échouer le chargement de la configuration avec CONFIG_INVALID, en nommant le chemin résolu.

La façon dont le glossaire est appliqué dépend du fournisseur : les fournisseurs LLM reçoivent la carte résolue avec la requête et ont pour instruction de traiter ses termes comme contraignants, tandis que DeepL ignore une carte de termes et applique à la place un glossaire configuré par id. Voir Fournisseurs.

tone

L'un de "formal", "informal" ou "neutral". Les fournisseurs LLM le reçoivent avec la requête et ont pour instruction de le respecter ; DeepL le mappe sur son réglage de formalité. Voir Fournisseurs pour les détails par fournisseur, y compris la dégradation de l'offre gratuite de DeepL.

prune

Désactivé par défaut. Quand il vaut true, les clés présentes dans un fichier cible mais absentes de la source (les clés orphelines de la comparaison) sont supprimées du fichier écrit et du fichier de verrouillage. Seules les clés orphelines sont jamais supprimées. Une option prune par exécution sur translate (l'option CLI --prune) prime sur la valeur de la configuration.

generatePlurals

Désactivé par défaut. Quand il vaut true, verbatra synthétise les formes plurielles CLDR qu'une langue cible exige mais que la source ne fournit pas (par exemple few et many pour le polonais). Pris en charge uniquement pour les projets i18next-JSON traduits par un fournisseur LLM ; DeepL, les formats non i18next et les langues cibles inconnues retombent sur l'avertissement de pluriel par locale. Il n'y a pas d'option CLI, donc règle ça dans la configuration ; l'entrée de translate() dans le SDK accepte une surcharge generatePlurals par exécution, qui prime.

maxBatchSize

Défaut 50. Les entrées manquantes plus modifiées d'une locale sont découpées en sous-lots séquentiels pas plus grands que ça, pour qu'une requête fournisseur trop grosse ne puisse pas faire échouer toute la locale. Un sous-lot échoué est retenu et retenté à l'exécution suivante pendant que les autres avancent quand même. Doit être un entier positif ; zéro, négatif ou fractionnaire est rejeté. Configuration uniquement : pas d'option CLI ni de surcharge par exécution.

maxTokens et budgetBehavior

maxTokens est un budget de tokens pour toute l'exécution : tokens d'entrée plus de sortie, sommés sur chaque appel fournisseur (traduction principale et génération de pluriels confondues) et sur chaque locale cible. Il est vérifié après chaque sous-lot terminé, jamais à l'intérieur d'un, donc le sous-lot dont l'achèvement franchit le plafond a déjà été envoyé, est accepté normalement, et ses tokens comptent quand même : un plafond souple a posteriori, pas une pré-vérification dure. Configuration uniquement, pas d'option CLI.

budgetBehavior décide de ce qui se passe une fois le plafond atteint :

• "warn" (le défaut) signale le dépassement et laisse l'exécution continuer exactement comme si aucun budget n'était configuré.
• "stop" retient chaque clé pas encore tentée pour le reste de l'exécution : les candidates restantes de la locale en cours, et entièrement les candidates de chaque locale cible suivante (leur comparaison et leur rapport d'orphelines tournent quand même ; seul l'appel fournisseur est sauté). Les clés retenues gardent leur hash de verrouillage précédent et sont retentées automatiquement à l'exécution suivante, comme un appel fournisseur échoué l'est déjà.

Un déclenchement du budget ne change jamais le code de sortie de la commande, dans aucun des deux comportements. budgetBehavior sans maxTokens est accepté et n'a aucun effet. Face à un fournisseur sans tokens (DeepL, qui ne rapporte aucun usage à mesurer), le garde-fou se déclare inerte (supported: false sur le budget du résumé d'exécution) plutôt que de produire un faux déclenchement.

Ordre de découverte

verbatra cherche vers le haut depuis le répertoire de travail et utilise la première source qu'il trouve. Plusieurs sources présentes ne sont pas une erreur ; la première correspondance gagne. L'ordre de recherche est :

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

Pour charger un fichier explicite au lieu de chercher, passe --config <path> ; un chemin relatif se résout contre le répertoire de travail. Dans le SDK, un configOverride en mémoire prime sur un configPath explicite, qui prime sur la recherche. Voir API programmatique.

Le répertoire de travail et .env

Lance verbatra depuis la racine de ton projet, ou passe --cwd pointant dessus. Le répertoire de travail est l'ancre unique de tout ce que verbatra résout : la recherche de configuration y démarre et remonte, .env.local et .env y sont chargés, et chaque chemin de fichier de locale se résout contre lui. Garder les trois au même endroit est ce qui fait qu'un simple verbatra translate fonctionne.

La précédence d'environnement est, du plus fort au plus faible : une variable déjà définie dans ton environnement réel, puis .env.local, puis .env. Une variable déjà présente n'est jamais écrasée.

Quand le chargement échoue

Le chargement de la configuration échoue avec l'un de deux codes d'erreur structurés :

• CONFIG_NOT_FOUND : la recherche n'a trouvé aucune configuration à aucun des endroits ci-dessus, ou le chemin explicite --config n'existe pas.
• CONFIG_INVALID : une configuration a été trouvée mais n'a pas pu être utilisée. Cela couvre un fichier qui ne s'analyse pas, une configuration qui échoue à la validation de schéma, et un chemin de fichier de glossaire qui n'a pas pu être résolu. Le message liste chaque problème de validation avec son chemin de clé, et une clé de premier niveau non reconnue reçoit en plus l'indice que les clés d'API sont lues depuis l'environnement, pas depuis la configuration. Une erreur brute d'analyseur ou de système de fichiers ne s'échappe jamais.

La CLI rapporte l'un ou l'autre échec et sort avec le code 2, le code de sortie des erreurs de frontière. Voir CI et codes de sortie.