FAQ

Des réponses rapides, chacune ancrée dans le comportement réel de verbatra. Pour une aide qui part des symptômes et des messages d'erreur, voir Dépannage.

Comment je contrôle le coût ?

Quatre leviers, tous sans appel fournisseur tant que tu n'en décides pas autrement :

• Les exécutions sont incrémentales par défaut : seules les clés manquantes ou dont la source a changé depuis la référence du fichier de verrouillage sont envoyées au fournisseur. Un projet inchangé ne coûte rien à relancer.
• --dry-run (ou translate({ config, dryRun: true })) prévisualise exactement ce qui serait envoyé, sans appel fournisseur et sans écriture.
• maxTokens dans la configuration fixe un plafond de tokens pour toute l'exécution, avec budgetBehavior qui décide de ce qui se passe quand il est atteint : "warn" (le défaut) le signale et continue, "stop" retient chaque clé pas encore tentée ; les clés retenues sont retentées automatiquement à l'exécution suivante.
• Gemini a une vraie offre d'API gratuite, et le fournisseur openai-compatible tourne contre un modèle local à coût d'API nul.

Combien coûte réellement une exécution ?

Un exemple chiffré, pour donner un ordre de grandeur. Un projet de 400 clés à traduire vers 3 langues, avec le maxBatchSize par défaut de 50, envoie 8 requêtes par langue, soit 24 au total. À environ 4 caractères par token, avec des valeurs source de 40 caractères et des noms de clés de 20, cela fait à peu près 32 400 tokens d'entrée et 22 800 tokens de sortie, donc environ 55 000 tokens pour toute l'exécution. Sur gemini-2.5-flash, à un tarif illustratif de $0.10 par million de tokens d'entrée et $0.40 par million de tokens de sortie, cela revient à environ 1,2 centime.

Les hypothèses derrière ce chiffre, pour que tu le remettes à l'échelle de ton projet : 400 clés par langue et 3 langues ; des valeurs de 40 caractères et des noms de clés de 20 ; pas de description, meaning, glossaire ni ton ; maxBatchSize à sa valeur par défaut ; 4 caractères par token ; des traductions à peu près aussi longues que leur source. Le tarif est un espace réservé qui rend le calcul concret, pas un prix cité : consulte le vrai sur la page tarifaire de ton fournisseur, car verbatra ne suit pas les tarifs des fournisseurs et ceux-ci changent.

Deux choses pèsent plus sur la facture réelle que le nombre de clés. Chaque requête porte une surcharge constante d'environ 350 tokens (les règles système fixes et le schéma de sortie) : un maxBatchSize plus grand répartit donc cette constante sur davantage de clés, et un plus petit coûte proportionnellement plus. Et ce chiffre n'est que le coût de la première exécution : les exécutions sont incrémentales, donc au quotidien tu paies pour la poignée de chaînes que tu as modifiées, pas pour tout le fichier. DeepL n'entre pas du tout dans cette formule, puisqu'il facture des caractères source plutôt que des tokens.

Voir Estimer le coût pour la méthode, le cas de la traduction automatique et la façon de calibrer sur une exécution réelle mesurée.

Avec quel fournisseur commencer ?

Gemini : il a une offre d'API gratuite, donc tu peux traduire un projet entier sans frais, et changer plus tard revient à modifier un seul id dans la configuration. Anthropic et OpenAI sont les choix qualité en LLM payant, DeepL et Google Cloud Translation sont les options de traduction automatique dédiées, et openai-compatible garde tout sur ton propre matériel. Voir Fournisseurs pour la comparaison complète.

Je peux faire tourner un modèle local ?

Oui. Le fournisseur openai-compatible pointe verbatra vers n'importe quel serveur qui parle l'API de chat d'OpenAI, comme LM Studio, Ollama ou vLLM, via son option baseUrl. La plupart des serveurs locaux n'ont besoin d'aucune clé d'API : quand ni une variable nommée par apiKeyEnvVar ni OPENAI_COMPATIBLE_API_KEY n'est définie, verbatra envoie le placeholder fixe "local". Si ton serveur a besoin d'une clé, nomme sa variable d'environnement avec apiKeyEnvVar.

Comment les clés gardent-elles leur ordre ?

Les adaptateurs de la famille JSON, YAML et ARB font l'aller-retour des fichiers exactement dans l'ordre du document : les clés existantes gardent leurs positions (y compris les clés de type entier), et les nouvelles clés sont ajoutées dans l'ordre de la source. Un fichier traduit se compare proprement avec sa version précédente. Voir Formats.

Pourquoi une traduction a-t-elle été signalée pour révision ?

Les traductions acceptées passent par des heuristiques de révision qui signalent les résultats suspects sans les retenir : une longueur très disproportionnée par rapport à la source (LENGTH_RATIO_OUTLIER), une traduction identique à la source (EQUALS_SOURCE), un terme de glossaire manqué (GLOSSARY_TERM_MISSED), des placeholders réordonnés (INTEGRITY_REORDERED), ou un chemin fournisseur dégradé (PROVIDER_DEGRADED). Les signalements atterrissent sur la liste needsReview du résumé d'exécution et dans la file de révision de Studio. Voir Sûreté de la traduction.

verbatra fonctionne-t-il dans un monorepo ?

Oui. La recherche de configuration démarre dans le répertoire de travail courant et remonte, donc lancer depuis le répertoire d'un paquet trouve la configuration de ce paquet. Depuis n'importe où ailleurs, passe --cwd <dir> (chaque commande le prend en charge) ou pointe vers un fichier précis avec --config <path>. Dans le SDK, les mêmes leviers sont cwd et configPath sur loadConfig. Le files.pattern et le fichier de verrouillage se résolvent contre le répertoire de travail.

Que dois-je commiter ?

Commite tes fichiers de locale et verbatra.lock.json : le fichier de verrouillage enregistre, par clé, le hash du contenu source dont chaque traduction provient, et le commiter est ce qui rend les exécutions incrémentales et la détection de dérive opérantes partout, CI comprise. Ne commite pas .env, .env.local, .verbatra-local/ ni verbatra.cache.json ; verbatra init ajoute les quatre au .gitignore, et translate, watch et import complètent un .gitignore existant auquel il en manque un. Voir Le fichier de verrouillage.

Comment je retraduis tout ?

Supprimer le fichier de verrouillage ne le fait pas : sans référence, les clés qui existent à la fois dans la source et la cible comptent comme à jour, donc une exécution après suppression du fichier de verrouillage ne traduit rien. Pour reconstruire une locale de zéro, supprime le fichier de cette locale et lance verbatra translate : chaque clé est alors manquante et se fait traduire à neuf. Pour une seule clé, utilise l'action de retraduction de Studio ou le retranslateEntry du SDK. Pour retraduire les clés dont le texte source a changé, lance simplement translate : c'est le chemin incrémental normal.

Utiliser la CLI implique-t-il d'installer le SDK ?

@verbatra/cli dépend de @verbatra/sdk, donc installer la CLI amène le SDK automatiquement ; il n'y a rien de plus à installer. L'inverse tient aussi : le SDK fonctionne seul dans tes propres scripts, sans CLI. Seul @verbatra/studio est une installation séparée, optionnelle, chargée dynamiquement par la commande studio.

Où vivent les clés d'API ?

Uniquement dans des variables d'environnement : ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPL_API_KEY ou GOOGLE_TRANSLATE_API_KEY, plus la variable que tu nommes pour openai-compatible. translate, watch, doctor et studio chargent .env et .env.local depuis le répertoire de travail (les vraies variables d'environnement gagnent). Le schéma de configuration rejette les clés inconnues précisément pour qu'un secret ne puisse pas finir dans un fichier commité, et les messages d'erreur nomment la variable mais jamais une valeur. Voir Fournisseurs.

Que vérifie réellement verbatra doctor ?

Cinq choses, toutes sans appel au fournisseur, sans requête réseau et sans lire la valeur d'une clé d'API :

• Configuration : la configuration se charge et passe la validation.
• Format adapter : le format configuré se résout en un adaptateur de fichier.
• Provider : le provider.id configuré se résout en une factory de fournisseur.
• API key environment variable : la variable d'environnement dont ce fournisseur lit sa clé est définie (vérifiée seulement par son nom, jamais par sa valeur).
• Source locale file : le fichier de la locale source existe, est un fichier normal et se parse sous le format configuré.

Chaque vérification s'exécute même si une précédente a échoué, une exécution rapporte donc tous les problèmes indépendants à la fois ; l'exception est la configuration elle-même : si elle échoue au chargement, les quatre vérifications qui en ont besoin sont sautées.

verbatra doctor

Utilise-le sur un checkout tout frais, juste après verbatra init, ou chaque fois qu'une autre commande a échoué et que tu veux la liste complète plutôt que la première erreur seulement. Voir verbatra doctor pour le tableau complet des vérifications et les codes de sortie.

Un agent IA peut-il configurer ou piloter verbatra à ma place ?

Quatre surfaces différentes pour quatre tâches différentes. Configure verbatra avec un agent IA est un prompt prêt à copier-coller pour Claude Code, Cursor ou tout agent de code capable de lire ton projet et d'exécuter des commandes shell : il inspecte une configuration i18n existante, installe la CLI, génère une configuration adaptée, exécute doctor, check, diff et translate --dry-run pour montrer le travail, puis s'arrête pour demander confirmation à un humain avant d'appeler pour de vrai un fournisseur. Recettes pour agents et scripts est la référence pour construire ta propre boucle d'agent sur la même enveloppe --json et les mêmes codes de sortie qu'utilisent ces commandes. Piloter Studio avec un agent de navigateur est encore une autre surface : un flag optionnel --expose-agent-tools sur verbatra studio qui enregistre des outils WebMCP pour qu'un agent IA dans le navigateur puisse piloter un projet déjà configuré depuis un onglet ouvert et authentifié du tableau de bord ; ce n'est explicitement pas pour la configuration initiale. verbatra mcp est la quatrième : un serveur MCP en stdio pour un client MCP hébergé dans un terminal ou headless (Claude Desktop, Claude Code, Cursor) qui veut les mêmes outils de statut, de glossaire et d'édition sans aucun navigateur.

Aucune des quatre ne donne à un agent le moyen de dépenser sans un humain dans la boucle. translate lui-même n'a aucune barrière de dépense propre, donc chaque surface orientée agent place une étape de confirmation, ou un flag --allow-spend, entre l'agent et un véritable appel au fournisseur.

Ce site publie-t-il quelque chose pour les agents IA et les robots d'indexation ?

Oui, trois fichiers statiques, générés au moment du build et toujours en anglais, quelle que soit la locale que tu consultes :

• /llms.txt : un index organisé avec le titre et la description de chaque page de documentation, groupé comme la barre latérale, sous forme de liens Markdown.
• /llms-full.txt : toute la documentation dans un seul fichier, le contenu rendu de chaque page concaténé dans l'ordre, pour un agent qui ingère le contenu directement plutôt que de suivre des liens.
• /.well-known/ai.txt : une politique d'usage qui indique aux robots d'indexation IA que ce projet est sous licence MIT et que crawler, indexer et citer ce contenu est bienvenu.

Les trois sont accessibles depuis la colonne du pied de page dédiée aux agents IA.

Le contenu de ce site est-il traduit par IA ?

Oui, les deux moitiés, par deux mécanismes différents. Le texte de l'interface (libellés de navigation, boutons, le pied de page, le texte de la landing page, la FAQ de la landing page) vit dans messages/en.json et ses fichiers frères de, es et fr ; ceux-ci sont traduits automatiquement avec verbatra lui-même, contre le format next-intl-json, via le fournisseur Gemini, exécuté par pnpm i18n dès que la source anglaise change. C'est le projet qui utilise ici son propre outil (dogfooding). La prose de la documentation que tu lis en ce moment, chaque guide et chaque page de référence y compris celle-ci, est du MDX à suffixe de locale (page.mdx, page.de.mdx, page.es.mdx, page.fr.mdx) et elle aussi traduite par IA, mais en dehors de cette chaîne automatisée : pnpm i18n ne traduit que les fichiers JSON, XLIFF, YAML, ARB et properties, jamais le Markdown, donc il ne touche jamais ces pages. Traduire une page de documentation est une étape séparée et manuelle à chaque changement de la source anglaise.

Si quelque chose sonne bizarre en allemand, en espagnol ou en français, ouvre une issue dans les deux cas : le texte de l'interface est corrigé à la source anglaise puis retraduit automatiquement par pnpm i18n ; pour la prose de la documentation, modifie le fichier MDX directement et envoie une pull request.