Fournisseurs

Sélectionne un fournisseur par id dans le bloc provider de ta configuration. Anthropic, OpenAI, Gemini, OpenCode et openai-compatible sont des modèles de langage ; DeepL, Google Cloud Translation et LibreTranslate sont des services de traduction automatique ; none désactive la traduction automatique. La couverture des langues se trouve dans Langues et locales, et ce que reçoit chaque fournisseur dans Traitement des données et confidentialité.

Lequel choisir ?Copier le lien vers cette section

Tout fournisseur fonctionne avec tout format et toute commande, et en changer plus tard revient à modifier un seul id.

Les clés viennent de l'environnementCopier le lien vers cette section

verbatra ne lit jamais une clé depuis la configuration. Chaque fournisseur hébergé lit une variable :

Définis-la dans .env (que verbatra init ajoute au .gitignore), dans ton shell ou dans le coffre de secrets de ta CI, et ne la commite jamais. Une variable absente ou vide échoue avec MISSING_API_KEY, en nommant la variable mais jamais une valeur. openai-compatible et libretranslate n'ont généralement besoin d'aucune clé.

AnthropicCopier le lien vers cette section

provider: {
  id: "anthropic",
  options: {
    model: "claude-sonnet-4-6", // example model id
    maxTokens: 4096,
  },
}

Lit ANTHROPIC_API_KEY.

OpenAICopier le lien vers cette section

provider: {
  id: "openai",
  options: {
    model: "gpt-5.4-mini", // example model id
    maxOutputTokens: 4096,
  },
}

Lit OPENAI_API_KEY.

GeminiCopier le lien vers cette section

provider: {
  id: "gemini",
  options: {
    model: "gemini-2.5-flash", // example model id
    maxOutputTokens: 4096,
  },
}

Lit GEMINI_API_KEY.

DeepLCopier le lien vers cette section

provider: {
  id: "deepl",
  options: {
    glossaryId: "<your-glossary-id>",
  },
}

Lit DEEPL_API_KEY ; options peut valoir {}. DeepL n'a ni modèle ni limite de tokens de sortie, et se dégrade avec un avis plutôt que d'échouer :

• Les placeholders voyagent comme des marqueurs numérotés dans une balise ignorée (Hello {{name}} comme Hello <x>{0}</x>) puis sont restaurés. PLACEHOLDER_UNSUPPORTED retient une valeur avec un placeholder non littéral ou avec <, >, { ou } dans le reste du texte, et un résultat avec un marqueur perdu, répété, modifié ou nu, une entité inconnue ou une balise étrangère. Le balisage seul part en texte brut.
• Le ton se mappe sur la formalité (formal plus formel, informal moins, neutral omis). Une clé de l'offre gratuite n'envoie aucune formalité et signale FORMALITY_DOWNGRADED. Une clé payante la demande avec prefer_more ou prefer_less, donc une langue sans formalité, comme le suédois, retombe sur le registre par défaut avec le même avis au lieu d'échouer. Le glossaire n'est pas appliqué.

verbatra embarque la table de langues datée de DeepL et refuse une langue non listée avec LOCALE_UNSUPPORTED_BY_PROVIDER avant toute dépense. Un glossaryId ne fonctionne que si les deux langues figurent dans la liste des glossaires de DeepL (comme DE, EN, FR, JA, ZH).

Google Cloud TranslationCopier le lien vers cette section

provider: {
  id: "google-translate",
  options: {},
}

Lit GOOGLE_TRANSLATE_API_KEY, une clé d'API d'un projet Google Cloud où l'API Cloud Translation est activée. Seul Basic (v2) fonctionne : Advanced (v3) exige un compte de service.

• Les placeholders sont masqués comme pour DeepL, dans <span translate="no"> ; les sauts de ligne, tabulations et doubles espaces sont aussi retenus.
• Codes. Chaque code envoyé est vérifié comme du BCP 47 bien formé avant tout appel (en_US échoue avec INVALID_REQUEST). Les codes régionaux sont autorisés ; une paire que Google rejette échoue avec INVALID_REQUEST venant de l'API.

verbatra embarque la table de langues datée de Google et refuse une langue non listée avant toute dépense. Un code régional dont la langue n'est listée que dans son ensemble, comme de-AT, est envoyé tel qu'il est écrit avec un avertissement.

OpenCodeCopier le lien vers cette section

Seuls les modèles d'OpenCode Zen servis par /chat/completions fonctionnent ici (le tableau des modèles indique l'endpoint de chacun). OpenCode réserve Go et les modèles gratuits de Zen à ses propres clients.

provider: {
  id: "opencode",
  options: {
    model: "glm-5.3", // example: a Zen model served over Chat Completions
    maxOutputTokens: 4096,
  },
}

Endpoint fixe, sans baseUrl. Lit OPENCODE_API_KEY.

openai-compatibleCopier le lien vers cette section

Tout serveur qui parle l'API Chat Completions d'OpenAI : LM Studio, Ollama, vLLM, ou une API hébergée.

Le serveur doit servir Chat Completions à <baseUrl>/chat/completions avec une sortie en JSON schema strict. Les passerelles qui ne servent que leurs propres applications clientes ne fonctionnent pas.

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "http://192.168.178.74:1234/v1",
    model: "qwen2.5-14b-instruct", // example: whatever your server exposes
    maxOutputTokens: 1024,
  },
}

Pour une API hébergée comme Mistral :

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "https://api.mistral.ai/v1",
    model: "mistral-large-latest", // example: check Mistral's current model list
    maxOutputTokens: 4096,
    apiKeyEnvVar: "MISTRAL_API_KEY",
  },
}

La réponse suit le même schéma strict que openai ; le premier objet JSON équilibré est pris dans toute prose ou bloc de code qui l'entoure, puis validé. verbatra init --provider openai-compatible --base-url <url> --model <name> écrit ce bloc (init), et --api-key-env-var <NAME> ajoute le nom de la variable.

Les clés sont optionnellesCopier le lien vers cette section

La clé se résout dans cet ordre :

1. apiKeyEnvVar : s'il est défini, sa variable doit contenir une clé, sinon l'exécution échoue avec MISSING_API_KEY.
2. OPENAI_COMPATIBLE_API_KEY : utilisée quand elle est définie et non vide.
3. "local" : un placeholder fixe et non secret, qui est ce qui fait fonctionner un serveur sans clé.

apiKeyEnvVar ne peut pas nommer la variable d'un fournisseur hébergé, et le client ne lit jamais OPENAI_API_KEY, donc une clé hébergée n'atteint jamais un baseUrl personnalisé.

Choisir un modèle localCopier le lien vers cette section

Préfère un modèle multilingue ajusté par instructions et sans raisonnement, aussi grand que ton matériel l'exécute bien, comme qwen2.5-14b-instruct. Les modèles de raisonnement et les builds fortement quantifiés ont tendance à envelopper ou tronquer la réponse, ce qui échoue en INVALID_RESPONSE ou OUTPUT_TRUNCATED.

LibreTranslateCopier le lien vers cette section

Un serveur LibreTranslate auto-hébergé (Argos Translate, sans modèle de langage). verbatra appelle seulement son API HTTP, donc la licence AGPL-3.0 du serveur ne s'étend pas à ton projet.

provider: {
  id: "libretranslate",
  options: {
    baseUrl: "http://localhost:5000",
  },
}

Ses langues sont les modèles installés sur ton serveur :

docker run -p 5000:5000 libretranslate/libretranslate --load-only en,de,fr

• Clé. LIBRETRANSLATE_API_KEY est envoyée comme api_key seulement si elle est définie. Un serveur démarré avec --api-keys fait échouer l'exécution avec MISSING_API_KEY quand elle est absente, et avec AUTH_FAILED quand il la rejette.
• Les placeholders sont masqués comme pour DeepL, par de simples marqueurs {0} ; le balisage est conservé, donc seules les accolades à côté d'un placeholder comptent.
• Balisage. Une valeur avec des balises de style HTML est envoyée au format html : le texte dans les balises est traduit, les balises restent (une formulation qui traverse une balise peut en souffrir) et des balises modifiées sont refusées.
• Vérification des langues. Chaque cible avertit LOCALE_UNVERIFIED_BY_PROVIDER à chaque exécution ; verbatra doctor --locales --live les vérifie auprès du serveur.

verbatra init --provider libretranslate --base-url <url> écrit ce bloc.

noneCopier le lien vers cette section

Désactive la traduction automatique par principe, pour une règle qui interdit d'envoyer des chaînes à un service.

provider: { id: "none" }

options peut être omis ou valoir {}. Aucun fournisseur n'est construit, aucune clé n'est lue et aucune requête n'est faite ; ce que fait chaque commande à la place est décrit dans Travailler sans traduction automatique.

Ton et glossaire selon les fournisseursCopier le lien vers cette section

Une requête ne porte que les termes du glossaire de sa locale cible, et chaque sortie est vérifiée par rapport à eux.

Comportement partagé par tous les fournisseursCopier le lien vers cette section

Découpage en lotsCopier le lien vers cette section

Le travail d'une locale part en sous-lots séquentiels d'au plus maxBatchSize entrées. Un sous-lot échoué est retenu et retenté à l'exécution suivante pendant que les autres avancent. DeepL et Google Cloud Translation découpent aussi un sous-lot pour respecter leurs propres plafonds par requête.

Nouvelles tentativesCopier le lien vers cette section

Les limites de débit et les erreurs serveur sont retentées avec backoff, par le client chez OpenAI, OpenCode, openai-compatible, Anthropic et DeepL et par verbatra pour Gemini. Google Cloud Translation et LibreTranslate ne réessaient pas. Gemini respecte une attente indiquée jusqu'à 5 secondes et fait échouer une attente plus longue, comme un quota quotidien épuisé, aussitôt avec RATE_LIMITED, qui nomme l'attente.

Délai de requêteCopier le lien vers cette section

requestTimeoutMs (120000 ms par défaut) empêche un serveur qui ne répond jamais de bloquer une exécution et de garder le verrou d'écriture d'une locale. Augmente-le pour un modèle local lent ou un gros maxBatchSize.

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "http://192.168.178.74:1234/v1",
    model: "qwen2.5-14b-instruct",
    maxOutputTokens: 1024,
    requestTimeoutMs: 300000, // 5 minutes
  },
}

• Par tentative. Chaque nouvelle tentative dispose du délai complet. Les fournisseurs LLM réessaient aussi une tentative qui a dépassé le délai, et tous sauf Gemini une erreur de connexion : un serveur figé met donc jusqu'à trois délais plus les pauses.
• L'erreur nomme la cause. TIMEOUT veut dire qu'une tentative n'a reçu aucune réponse à temps ; des connexions refusées répétées échouent en PROVIDER_ERROR.
• DeepL ne peut pas interrompre une requête en cours : une exécution interrompue la laisse donc aller à son terme chez DeepL.

Codes de locale envoyés au fournisseurCopier le lien vers cette section

Les fichiers, le fichier de verrouillage et la mémoire utilisent toujours les codes de ta configuration. Seule la requête est traduite vers ce qu'attend le fournisseur :

Un LLM reçoit aussi les noms de langue, d'écriture et de région. DeepL n'a pas de cible anglaise ni portugaise générique, donc une cible qui aboutit à un en ou pt nu (comme en-AU) est refusée avant l'exécution : fais-la correspondre à EN-GB, EN-US, PT-BR ou PT-PT.

localeMap remplace le code par locale :

provider: {
  id: "deepl",
  options: {
    localeMap: {
      "en-AU": "EN-GB",
      "fr-BE": "FR-FR",
    },
  },
}

• Les clés doivent être sourceLocale ou une locale cible comme dans la configuration, sinon la configuration échoue avec CONFIG_INVALID. La table se place sous options, pour tous les fournisseurs sauf none.
• Les valeurs sont des chaînes non vides de 64 caractères au plus, envoyées telles quelles : comme code de langue à un fournisseur de traduction automatique, à la place du code pour un LLM ("pt-BR (Brazilian Portuguese)" fonctionne), dont les noms de langue viennent toujours de la clé. Un EN ou PT nu pour DeepL échoue avec INVALID_REQUEST ; une valeur que le fournisseur rejette fait échouer son sous-lot.
• Effet sur la mémoire. Seules les chaînes nouvelles et modifiées partent avec un nouveau code. Une table non vide fait partie de l'empreinte de la mémoire, donc la modifier ouvre un compartiment séparé.

Vérifier les langues prises en charge par un fournisseurCopier le lien vers cette section

Chaque locale configurée est jugée avant toute dépense :

Une locale non prise en charge est refusée avec LOCALE_UNSUPPORTED_BY_PROVIDER (code de sortie 2) avant qu'aucun fournisseur ne soit construit ; un avertissement ne refuse jamais et apparaît comme avis. verbatra doctor donne chaque verdict, et son option --live vérifie la liste actuelle du fournisseur, mais translate utilise toujours la table embarquée. Pour une langue ajoutée depuis, associe la locale dans localeMap : un code explicite est envoyé avec un avertissement, pas refusé.

Erreurs structuréesCopier le lien vers cette section

Un échec de fournisseur remonte comme une erreur structurée, sans secret, qui ne touche que son propre sous-lot. Un PROVIDER_ERROR ne nomme que l'hôte et le port d'un baseUrl openai-compatible ou LibreTranslate, et pour Google que translation.googleapis.com, jamais la chaîne de requête qui porte sa clé.

Limites de tokens de sortieCopier le lien vers cette section

Les fournisseurs LLM plafonnent les tokens de chaque réponse ; un modèle qui s'arrête au plafond lève OUTPUT_TRUNCATED. verbatra redécoupe un sous-lot tronqué en deux moitiés, en descendant jusqu'à une seule entrée, et ne retient qu'une entrée qui déborde encore. Pour régler cela durablement, baisse maxBatchSize ou augmente maxTokens (Anthropic) ou maxOutputTokens. Un modèle de raisonnement puise ses tokens de raisonnement cachés dans le même budget : donne-lui donc une marge généreuse.

Signalements de relectureCopier le lien vers cette section

Une traduction suspecte est signalée pour relecture, quel que soit le fournisseur, plutôt que rejetée. Voir les raisons de relecture et Réviser dans Studio.