Provider

Wähle einen Provider über die id im provider-Block deiner Konfiguration. Anthropic, OpenAI, Gemini, OpenCode und openai-compatible sind Sprachmodelle; DeepL, Google Cloud Translation und LibreTranslate sind Maschinenübersetzungsdienste; none schaltet maschinelle Übersetzung ab. Die Sprachabdeckung steht unter Sprachen und Locales, und was jeder Provider bekommt, unter Datenverarbeitung und Datenschutz.

Welchen soll ich nehmen?Link zu diesem Abschnitt kopieren

Jeder Provider funktioniert mit jedem Format und jedem Befehl, und ein späterer Wechsel heißt, eine id zu ändern.

Keys kommen aus der UmgebungLink zu diesem Abschnitt kopieren

verbatra liest nie einen Key aus der Konfiguration. Jeder gehostete Provider liest eine Variable:

Setze sie in .env (das verbatra init in .gitignore einträgt), in deiner Shell oder in deinem CI-Secret-Store, und committe sie nie. Eine ungesetzte oder leere Variable scheitert mit MISSING_API_KEY, das die Variable nennt, aber nie einen Wert. openai-compatible und libretranslate brauchen meist keinen Key.

AnthropicLink zu diesem Abschnitt kopieren

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

Liest ANTHROPIC_API_KEY.

OpenAILink zu diesem Abschnitt kopieren

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

Liest OPENAI_API_KEY.

GeminiLink zu diesem Abschnitt kopieren

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

Liest GEMINI_API_KEY.

DeepLLink zu diesem Abschnitt kopieren

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

Liest DEEPL_API_KEY; options darf {} sein. DeepL hat kein Modell und kein Ausgabe-Token-Limit und stuft mit einem Hinweis herab, statt fehlzuschlagen:

• Platzhalter reisen als nummerierte Markierungen in einem ignorierten Tag (Hello {{name}} als Hello <x>{0}</x>) und werden wieder eingesetzt. PLACEHOLDER_UNSUPPORTED hält einen Wert mit nicht wörtlichem Platzhalter oder mit <, >, { oder } im übrigen Text zurück, und ein Ergebnis mit verlorener, wiederholter, geänderter oder bloßer Markierung, unbekannter Entity oder fremdem Tag. Reines Markup geht als Klartext hinaus.
• Tonfall wird auf Formalität abgebildet (formal formeller, informal informeller, neutral weggelassen). Ein Key aus dem kostenlosen Kontingent sendet gar keine Formalität und meldet FORMALITY_DOWNGRADED. Ein bezahlter Key fragt mit prefer_more oder prefer_less an, sodass eine Sprache ohne Formalität wie Schwedisch mit demselben Hinweis zurückfällt statt zu scheitern. Das Glossar wird nicht angewendet.

verbatra liefert DeepLs datierte Sprachtabelle mit und lehnt eine nicht aufgeführte Sprache mit LOCALE_UNSUPPORTED_BY_PROVIDER ab, bevor etwas ausgegeben wird. Eine glossaryId funktioniert nur, wenn beide Sprachen auf DeepLs Glossarliste stehen (etwa DE, EN, FR, JA, ZH).

Google Cloud TranslationLink zu diesem Abschnitt kopieren

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

Liest GOOGLE_TRANSLATE_API_KEY, einen API-Schlüssel für ein Google-Cloud-Projekt mit aktivierter Cloud Translation API. Nur Basic (v2) funktioniert: Advanced (v3) braucht einen Service-Account.

• Platzhalter werden wie bei DeepL maskiert, in <span translate="no">; Zeilenumbrüche, Tabs und doppelte Leerzeichen werden ebenfalls zurückgehalten.
• Codes. Jeder gesendete Code wird vor jedem Aufruf als wohlgeformtes BCP 47 geprüft (en_US scheitert mit INVALID_REQUEST). Regionale Codes sind erlaubt; ein Paar, das Google ablehnt, scheitert mit INVALID_REQUEST von der API.

verbatra liefert Googles datierte Sprachtabelle mit und lehnt eine nicht aufgeführte Sprache ab, bevor etwas ausgegeben wird. Ein regionaler Code, dessen Sprache nur als Ganzes aufgeführt ist, etwa de-AT, wird mit einer Warnung so gesendet, wie er geschrieben ist.

OpenCodeLink zu diesem Abschnitt kopieren

Hier funktionieren nur Modelle von OpenCode Zen, die über /chat/completions laufen (die Modelltabelle nennt den Endpunkt jedes Modells). OpenCode behält Go und die kostenlosen Zen-Modelle seinen eigenen Clients vor.

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

Fester Endpunkt, kein baseUrl. Liest OPENCODE_API_KEY.

openai-compatibleLink zu diesem Abschnitt kopieren

Jeder Server, der die OpenAI-Chat-Completions-API spricht: LM Studio, Ollama, vLLM oder eine gehostete API.

Der Server muss Chat Completions unter <baseUrl>/chat/completions mit striktem JSON-Schema-Output bereitstellen. Gateways, die nur ihre eigenen Client-Apps bedienen, funktionieren nicht.

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,
  },
}

Für eine gehostete API wie 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",
  },
}

Die Antwort nutzt dasselbe strikte Schema wie openai; das erste balancierte JSON-Objekt wird aus umgebender Prosa oder einem Code-Fence genommen und validiert. verbatra init --provider openai-compatible --base-url <url> --model <name> schreibt diesen Block (init), und --api-key-env-var <NAME> ergänzt den Namen der Variable.

Keys sind optionalLink zu diesem Abschnitt kopieren

Der Key wird der Reihe nach aufgelöst:

1. apiKeyEnvVar: Wenn gesetzt, muss seine Variable einen Key enthalten, sonst scheitert der Lauf mit MISSING_API_KEY.
2. OPENAI_COMPATIBLE_API_KEY: wird verwendet, wenn sie gesetzt und nicht leer ist.
3. "local": ein fester, nicht geheimer Platzhalter, der einen Server ohne Key funktionieren lässt.

apiKeyEnvVar kann nicht die Variable eines gehosteten Providers nennen, und der Client liest nie OPENAI_API_KEY, ein gehosteter Key erreicht also nie eine eigene baseUrl.

Ein lokales Modell wählenLink zu diesem Abschnitt kopieren

Bevorzuge ein instruktionsoptimiertes, mehrsprachiges Modell ohne Reasoning, so groß, wie deine Hardware es gut ausführt, etwa qwen2.5-14b-instruct. Reasoning-Modelle und stark quantisierte Builds neigen dazu, die Antwort zu verpacken oder abzuschneiden, was als INVALID_RESPONSE oder OUTPUT_TRUNCATED scheitert.

LibreTranslateLink zu diesem Abschnitt kopieren

Ein selbst gehosteter LibreTranslate-Server (Argos Translate, kein Sprachmodell). verbatra ruft nur seine HTTP-API auf, die AGPL-3.0-Lizenz des Servers erstreckt sich also nicht auf dein Projekt.

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

Seine Sprachen sind die auf deinem Server installierten Modelle:

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

• Key. LIBRETRANSLATE_API_KEY wird nur als api_key gesendet, wenn sie gesetzt ist. Ein mit --api-keys gestarteter Server lässt den Lauf mit MISSING_API_KEY scheitern, wenn sie nicht gesetzt ist, und mit AUTH_FAILED, wenn er sie ablehnt.
• Platzhalter werden wie bei DeepL maskiert, als bloße {0}-Markierungen; Markup bleibt erhalten, daher zählen nur geschweifte Klammern neben einem Platzhalter.
• Markup. Ein Wert mit HTML-artigen Tags wird im html-Format gesendet: Der Text in den Tags wird übersetzt, die Tags bleiben (eine Formulierung über ein Tag hinweg kann leiden), und veränderte Tags werden abgelehnt.
• Sprachprüfung. Jedes Ziel warnt bei jedem Lauf LOCALE_UNVERIFIED_BY_PROVIDER; verbatra doctor --locales --live prüft sie gegen den Server.

verbatra init --provider libretranslate --base-url <url> schreibt diesen Block.

noneLink zu diesem Abschnitt kopieren

Schaltet maschinelle Übersetzung per Richtlinie ab, für eine Regel, die verbietet, Strings an irgendeinen Dienst zu senden.

provider: { id: "none" }

options darf fehlen oder {} sein. Es wird kein Provider erzeugt, kein Key gelesen und keine Anfrage gestellt; was jeder Befehl stattdessen tut, steht unter Ohne maschinelle Übersetzung arbeiten.

Tonfall und Glossar über die Provider hinwegLink zu diesem Abschnitt kopieren

Eine Anfrage enthält nur die Glossarbegriffe ihrer Ziel-Locale, und jede Ausgabe wird gegen sie geprüft.

Verhalten, das jeder Provider teiltLink zu diesem Abschnitt kopieren

BatchingLink zu diesem Abschnitt kopieren

Die Arbeit einer Locale geht in sequenziellen Sub-Batches von höchstens maxBatchSize Einträgen hinaus. Ein fehlgeschlagener Sub-Batch wird zurückgehalten und beim nächsten Lauf erneut versucht, während der Rest weiter vorankommt. DeepL und Google Cloud Translation teilen einen Sub-Batch zusätzlich auf, damit er in ihre eigenen Anfragegrenzen passt.

WiederholungenLink zu diesem Abschnitt kopieren

Rate-Limits und Serverfehler werden mit Backoff wiederholt, bei OpenAI, OpenCode, openai-compatible, Anthropic und DeepL vom Client und bei Gemini von verbatra. Google Cloud Translation und LibreTranslate wiederholen nicht. Gemini hält eine genannte Wartezeit von bis zu 5 Sekunden ein und lässt eine längere, etwa bei erschöpftem Tageskontingent, sofort mit RATE_LIMITED scheitern, das die Wartezeit nennt.

Anfrage-TimeoutLink zu diesem Abschnitt kopieren

requestTimeoutMs (Default 120000 ms) verhindert, dass ein Server, der nie antwortet, einen Lauf blockiert und die Schreibsperre einer Locale hält. Erhöhe ihn für ein langsames lokales Modell oder eine große 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
  },
}

• Pro Versuch. Jede Wiederholung bekommt den vollen Timeout. Die LLM-Provider wiederholen auch einen Versuch im Timeout, und alle außer Gemini einen Verbindungsfehler, ein hängender Server braucht also bis zu drei Timeouts plus Backoff.
• Der Fehler nennt die Ursache. TIMEOUT heißt, dass ein Versuch rechtzeitig keine Antwort bekommen hat; wiederholt abgelehnte Verbindungen scheitern als PROVIDER_ERROR.
• DeepL kann eine laufende Anfrage nicht abbrechen, ein unterbrochener Lauf lässt sie also bei DeepL zu Ende laufen.

An den Provider gesendete Locale-CodesLink zu diesem Abschnitt kopieren

Dateien, Lock-Datei und Translation Memory verwenden immer die Codes deiner Konfiguration. Nur die Anfrage wird in das übersetzt, was der Provider erwartet:

Ein LLM bekommt zusätzlich die Namen von Sprache, Schrift und Region. DeepL hat kein allgemeines Englisch oder Portugiesisch als Ziel, ein Ziel, das am Ende ein bloßes en oder pt ist (etwa en-AU), wird deshalb vor dem Lauf abgelehnt: Bilde es auf EN-GB, EN-US, PT-BR oder PT-PT ab.

localeMap überschreibt den Code pro Locale:

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

• Keys müssen sourceLocale oder eine Ziel-Locale wie konfiguriert sein, sonst scheitert die Konfiguration mit CONFIG_INVALID. Die Zuordnung gehört unter options, bei jedem Provider außer none.
• Werte sind nicht leere Strings mit höchstens 64 Zeichen und werden unverändert gesendet: an einen Maschinenübersetzungs-Provider als Sprachcode, an ein LLM anstelle des Codes ("pt-BR (Brazilian Portuguese)" funktioniert), dessen Sprachnamen trotzdem aus dem Key kommen. Ein bloßes EN oder PT für DeepL scheitert mit INVALID_REQUEST; ein Wert, den der Provider ablehnt, lässt seinen Sub-Batch scheitern.
• Wirkung auf das Translation Memory. Nur neue und geänderte Strings gehen mit einem neuen Code hinaus. Ein nicht leeres localeMap ist Teil des Fingerprints im Translation Memory, eine Änderung beginnt also einen eigenen Bereich.

Die Sprachunterstützung eines Providers prüfenLink zu diesem Abschnitt kopieren

Jede konfigurierte Locale wird beurteilt, bevor etwas ausgegeben wird:

Eine nicht unterstützte Locale wird mit LOCALE_UNSUPPORTED_BY_PROVIDER (Exit 2) abgelehnt, bevor ein Provider erzeugt wird; eine Warnung lehnt nie ab und erscheint als Hinweis. verbatra doctor meldet jedes Urteil, und sein Flag --live prüft gegen die aktuelle Liste des Providers, aber translate verwendet immer die mitgelieferte Tabelle. Für eine seitdem ergänzte Sprache bilde die Locale in localeMap ab: Ein expliziter Code wird mit einer Warnung gesendet, nicht abgelehnt.

Strukturierte FehlerLink zu diesem Abschnitt kopieren

Ein Provider-Fehlschlag erscheint als strukturierter, geheimnisfreier Fehler, der nur seinen eigenen Sub-Batch betrifft. Ein PROVIDER_ERROR nennt nur Host und Port einer baseUrl von openai-compatible oder LibreTranslate, und bei Google nur translation.googleapis.com, nie den Query-String mit seinem Key.

Ausgabe-Token-LimitsLink zu diesem Abschnitt kopieren

Die LLM-Provider begrenzen die Tokens jeder Antwort; ein Modell, das an der Grenze stoppt, erzeugt OUTPUT_TRUNCATED. verbatra teilt einen abgeschnittenen Sub-Batch in Hälften, bis hinunter zu einem Eintrag, und hält nur einen Eintrag zurück, der weiterhin überläuft. Um das dauerhaft zu beheben, senke maxBatchSize oder erhöhe maxTokens (Anthropic) beziehungsweise maxOutputTokens. Ein Reasoning-Modell verbraucht verborgene Reasoning-Tokens aus demselben Budget, gib ihm also reichlich Spielraum.

Review-FlagsLink zu diesem Abschnitt kopieren

Eine verdächtige Übersetzung wird bei jedem Provider zum Review markiert, nicht abgelehnt. Siehe Review-Gründe und In Studio prüfen.