Provider

verbatra liefert fünf Provider hinter einer Schnittstelle: Anthropic, OpenAI, Gemini und openai-compatible (ein lokaler oder selbst gehosteter OpenAI-kompatibler Server) sind Large Language Models, und DeepL ist ein Maschinenübersetzungsdienst. Du wählst einen im provider-Block deiner Konfiguration, über die id. Jede Modell-Id auf dieser Seite ist ein Beispiel, keine Empfehlung: Modellkataloge ändern sich, prüfe also die aktuelle Liste deines Providers.

Welchen soll ich nehmen?

Jeder Provider funktioniert mit jedem Format und jedem Befehl; bei der Wahl geht es um Kosten, Qualität, Privatsphäre und darum, wie du an einen Schlüssel kommst.

• Kleines oder Nebenprojekt, und es soll kostenlos sein? Nimm Gemini. Es hat ein echtes kostenloses API-Kontingent, du kannst also eine ganze App zum Nulltarif übersetzen. Hol dir einen Schlüssel im Google AI Studio und setze GEMINI_API_KEY. Das kostenlose Kontingent ist ratenbegrenzt (siehe den Hinweis unten), was nur bei einem großen ersten Lauf ins Gewicht fällt.
• Beste Übersetzungsqualität für eine Produktions-App? Nimm Anthropic oder OpenAI. Beide sind bezahlte LLMs und lesen ANTHROPIC_API_KEY oder OPENAI_API_KEY.
• Hohes Volumen, glossargetrieben oder kein LLM im Spiel? Nimm DeepL. Es ist eine dedizierte Maschinenübersetzungs-API mit einem kostenlosen und einem bezahlten Kontingent und unterstützt ein natives Glossar per Id. Strings mit Platzhaltern übersetzt es nicht (siehe den Hinweis unten); nimm dafür einen LLM-Provider.
• Offline, kostenfrei, oder deine Strings dürfen dein Netzwerk nie verlassen? Nimm openai-compatible. Es richtet verbatra auf einen lokalen oder selbst gehosteten Inferenzserver (LM Studio, Ollama, vLLM) statt auf eine gehostete API. Kein Konto, kein API-Schlüssel und kein Netzwerkverkehr über deine eigene Maschine oder dein LAN hinaus.

Unsicher? Starte mit Geminis kostenlosem Kontingent und wechsle den Provider später, indem du eine id in deiner Konfiguration änderst. Sonst ändert sich nichts.

Schlüssel kommen aus der Umgebung

verbatra liest nie einen API-Schlüssel aus der Konfiguration. Jeder gehostete Provider liest genau eine Umgebungsvariable:

Setze die Variable in .env (das verbatra init in .gitignore einträgt) oder exportiere sie in deiner Shell oder deinem CI-Secret-Store. Ist die Variable ungesetzt oder leer, schlägt der Provider mit einem strukturierten MISSING_API_KEY-Fehler fehl, dessen Meldung die Variable nennt, aber nie einen Schlüsselwert enthält. Committe nie einen echten Schlüssel.

openai-compatible ist anders: Die meisten lokalen Server brauchen gar keinen Schlüssel, deshalb steht es nicht in dieser Tabelle. Wie seine Schlüsselauflösung funktioniert, steht in seinem eigenen Abschnitt unten.

Anthropic

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

Liest ANTHROPIC_API_KEY. model und maxTokens sind beide erforderlich. maxTokens begrenzt die Tokens, die eine einzelne Antwort erzeugen darf; es ist die Option dieses Providers für das Ausgabe-Token-Limit (die anderen nennen sie maxOutputTokens).

OpenAI

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

Liest OPENAI_API_KEY. model und maxOutputTokens sind beide erforderlich.

Gemini

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

Liest GEMINI_API_KEY. model und maxOutputTokens sind beide erforderlich.

DeepL

provider: {
  id: "deepl",
  options: {},
}

Liest DEEPL_API_KEY. DeepL ist eine Maschinenübersetzungs-API, kein LLM: Es hat kein model-Feld und kein Ausgabe-Token-Limit. Die einzige Option ist ein optionales glossaryId, das ein Glossar nennt, das du bereits in DeepL angelegt hast:

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

DeepL stuft kontrolliert herab, statt fehlzuschlagen, wenn es eine Einstellung nicht einhalten kann, und meldet jede Herabstufung als Hinweis am Lauf:

• Eine konfigurierte glossary-Begriffszuordnung wird nicht angewendet (DeepL nutzt nur eine vorab angelegte Glossar-Id), gemeldet als GLOSSARY_IGNORED.
• tone wird auf DeepLs Formalität abgebildet: formal wird formeller, informal wird informeller, neutral oder ein fehlender Ton wird weggelassen. Mit einem Schlüssel aus dem kostenlosen Kontingent wird Formalität nicht unterstützt, ein nicht-standardmäßiger Ton fällt also auf den Default zurück, gemeldet als FORMALITY_DOWNGRADED.

openai-compatible

Richtet verbatra auf einen Server, der die OpenAI-Chat-Completions-API spricht: LM Studio, Ollama, vLLM und ähnliche funktionieren alle. Die Id benennt das Protokoll auf der Leitung, nicht den Ort des Servers, eine gehostete API, die dasselbe Protokoll spricht, passt hier also auch.

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

baseUrl, model und maxOutputTokens sind erforderlich. Anders als bei jedem anderen Provider lebt baseUrl in der Konfiguration statt in der Umgebung: Es ist eine Netzwerkadresse, die du ohnehin kennst (eine LAN-IP oder localhost), kein Geheimnis. Der Wert muss eine gültige absolute URL mit http- oder https-Schema sein; alles andere, auch ein fehlendes Schema, lässt die Konfigurationsvalidierung sofort fehlschlagen.

baseUrl muss das API-Pfadsegment deines Servers enthalten, typischerweise /v1: LM Studio, Ollama und vLLM servieren ihre OpenAI-kompatiblen Routen alle unter /v1. Eine baseUrl ohne dieses Segment ist trotzdem eine syntaktisch gültige URL, besteht also die Konfigurationsvalidierung und schlägt stattdessen zur Anfragezeit fehl, weil sie den falschen Pfad erreicht.

Eine gehostete API, die dasselbe Protokoll spricht, funktioniert genauso. Mistrals Chat-Completions-API ist ein Beispiel:

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

apiKeyEnvVar nennt die Umgebungsvariable mit deinem Schlüssel für diesen Server. Das ist derselbe openai-compatible-Provider, auf einen anderen Endpunkt gerichtet, kein dedizierter Mistral-Provider.

Schlüssel sind optional

Die meisten lokalen Inferenzserver brauchen gar keinen API-Schlüssel, deshalb löst openai-compatible seinen Schlüssel in drei Stufen auf, der Reihe nach:

1. apiKeyEnvVar, ein optionales Konfigurationsfeld, das eine Umgebungsvariable nennt, aus der ein echter Schlüssel gelesen wird. Wenn du dieses Feld setzt und die genannte Variable ungesetzt oder leer ist, schlägt verbatra mit MISSING_API_KEY fehl, statt still zurückzufallen, denn du hast ausdrücklich gesagt, dass ein Schlüssel erforderlich ist.
2. OPENAI_COMPATIBLE_API_KEY, eine Konventionsvariable, gelesen, wenn apiKeyEnvVar nicht gesetzt ist. Ist sie gesetzt und nicht leer, verwendet verbatra sie; wenn nicht, macht verbatra ohne Fehler weiter.
3. Der Platzhalter "local", gesendet, wenn keine der beiden Stufen etwas ergibt. Das ist ein fester, nicht geheimer String, kein echter Schlüssel, und genau das, was einen schlüssellosen lokalen Server ohne jede Konfiguration funktionieren lässt.

apiKeyEnvVar kann nie ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY oder DEEPL_API_KEY nennen: Die Konfigurationsvalidierung lehnt das rundheraus ab, eine Konfiguration kann diesen Provider also nicht namentlich auf den Schlüssel eines gehosteten Providers richten. Der Client liest außerdem nie selbst OPENAI_API_KEY und übergibt dem darunterliegenden SDK immer einen expliziten Schlüsselwert, ein gehosteter Schlüssel kann also nie eine eigene baseUrl erreichen.

Ein lokales Modell wählen

Bevorzuge ein instruktionsoptimiertes Modell ohne Reasoning und mit guter mehrsprachiger Abdeckung. verbatra fordert ein einzelnes striktes JSON-Objekt an und validiert es, du willst also ein Modell, das Formatvorgaben zuverlässig befolgt. qwen2.5-14b-instruct ist ein sinnvoller Standard; wähle das größte solche Modell, das deine Hardware gut ausführt.

Ein schlechtes lokales Modell schlägt laut fehl, nicht still: verbatra validiert jede Provider-Antwort gegen ein kanonisches Schema sowie Platzhalter- und ICU-Integrität, ein Modell, das Reasoning-Prosa oder abgeschnittenes JSON ausgibt, wird also mit einem INVALID_RESPONSE- oder OUTPUT_TRUNCATED-Fehler abgelehnt, statt eine korrupte Übersetzung zu schreiben.

Tolerantes Parsen für lokale und kleinere Modelle

openai-compatible fordert dasselbe strikte, schemagebundene Antwortformat an wie der gehostete openai-Provider. Der eine Unterschied liegt auf dem Rückweg: Lokale und kleinere Modelle verpacken eine ansonsten korrekte Antwort eher in umgebende Prosa oder einen Markdown-Code-Fence, obwohl sie darum gebeten wurden, das zu lassen, deshalb extrahiert openai-compatible vor dem Parsen das erste balancierte JSON-Objekt an beliebiger Stelle der Antwort, was der gehostete Provider nicht tut. Seine Ausgabe durchläuft trotzdem exakt dieselbe Schemavalidierung und dieselben Platzhalter- und ICU-Integritätsprüfungen wie bei jedem anderen Provider: Die Ausgabe eines lokalen Modells ist nicht vertrauenswürdige Eingabe, und eine fehlerhafte Antwort oder eine mit abweichenden Platzhaltern wird genauso abgelehnt.

Ton und Glossar über die Provider hinweg

Die optionalen Konfigurationsfelder tone und glossary (siehe Konfigurationsdatei) werden pro Provider angewendet:

• Ton. Die LLM-Provider (Anthropic, OpenAI, Gemini und openai-compatible) erhalten den Ton mit der Anfrage und werden angewiesen, ihn einzuhalten. DeepL bildet ihn auf Formalität ab, mit der oben beschriebenen Herabstufung im kostenlosen Kontingent.
• Glossar. Die LLM-Provider erhalten die Begriffszuordnung und werden angewiesen, ihre Begriffe als bindend zu behandeln. DeepL ignoriert eine Begriffszuordnung (mit einem GLOSSARY_IGNORED-Hinweis) und wendet nur seine native glossaryId an.

Verhalten, das jeder Provider teilt

Batching

Die Arbeit einer Locale wird in sequenzielle Sub-Batches von höchstens maxBatchSize Einträgen aufgeteilt (Default 50; siehe Konfigurationsdatei), damit eine überdimensionierte Anfrage nicht die ganze Locale fehlschlagen lässt. Ein fehlgeschlagener Sub-Batch wird zurückgehalten und beim nächsten Lauf automatisch erneut versucht, während die anderen Sub-Batches weiter Fortschritt machen. DeepL teilt einen Sub-Batch zusätzlich transparent auf so viele Anfragen auf, wie seine eigenen Grenzen pro Anfrage verlangen.

Wiederholungen

Vorübergehende Fehlschläge (eine Rate-Limit-Antwort oder ein Serverfehler) werden automatisch mit kurzem Backoff wiederholt: Die SDK-Clients von OpenAI, Anthropic und DeepL wiederholen standardmäßig, und verbatra ergänzt eine gleichwertige eigene Wiederholung für Gemini, dessen SDK das nicht tut. Wiederholungen glätten momentane Aussetzer; ein anhaltender Fehlschlag taucht weiterhin als strukturierter Fehler auf.

Strukturierte Fehler

Ein Provider-Fehlschlag erscheint nie als roher SDK-Fehler, der Request-Header oder einen Schlüssel tragen könnte. verbatra klassifiziert jeden Fehlschlag über seinen HTTP-Status oder seine SDK-Fehlerklasse und erzeugt einen strukturierten Fehler mit einem stabilen Code und einer festen, geheimnisfreien Meldung:

Ein Fehlschlag betrifft nur seinen eigenen Sub-Batch: Die fehlgeschlagenen Keys werden zurückgehalten und beim nächsten Lauf wieder aufgegriffen.

Ausgabe-Token-Limits

Die vier LLM-Provider begrenzen, wie viele Tokens eine einzelne Antwort erzeugen darf. Stoppt ein Modell, weil es diese Grenze erreicht hat, erzeugt verbatra OUTPUT_TRUNCATED statt eines generischen Fehlers über eine fehlerhafte Antwort, mit einer festen Meldung:

The provider stopped because the output-token limit was reached. Reduce the batch size or raise the configured max output tokens.

Beide Hebel lösen das Problem: Senke maxBatchSize in deiner Konfiguration, damit jede Anfrage eine kleinere Antwort erzeugt, oder erhöhe die Grenze pro Antwort am Provider (maxTokens für Anthropic, maxOutputTokens für OpenAI, Gemini und openai-compatible). DeepL ist nicht betroffen: Es hat keinen Abschneidefall bei Ausgabe-Tokens. verbatra erholt sich außerdem von selbst: Wird ein Sub-Batch abgeschnitten, teilt verbatra ihn in Hälften und versucht es erneut, bis hinunter zu einem einzelnen Eintrag, sodass die Schlüssel, die in eine kleinere Anfrage passen, trotzdem übersetzt werden und nur ein einzelner Eintrag, der weiterhin überläuft, für den nächsten Lauf zurückgehalten wird.

Review-Flags

Die akzeptierten Übersetzungen jedes Providers durchlaufen dieselben Prüfungen nach der Übersetzung, und ein verdächtiges Ergebnis (zum Beispiel eines, das mit seiner Quelle identisch ist, oder eines, das einen Glossarbegriff verfehlt hat) wird in die Review-Warteschlange markiert statt abgelehnt. Die Grund-Codes und wie du die Warteschlange abarbeitest, stehen in Übersetzungssicherheit und Review in Studio.