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 DeepL 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 est l'option de traduction automatique dédiée, 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 ou DEEPL_API_KEY, plus la variable que tu nommes pour openai-compatible. translate, watch 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.