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.

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 ni .verbatra-local/ ; verbatra init ajoute les trois au .gitignore. 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. La CLI charge .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.