Lokalisieren

Du hast einen String oder ein kleines Objekt mit Strings, das sofort in einer anderen Sprache vorliegen muss – ein Formularlabel, eine Benachrichtigung oder einen kurzen UI-Text, auf den ein Nutzer gerade wartet. Für einen einzelnen Roundtrip willst du weder einen Webhook-Endpunkt aufsetzen noch einen Job pollen. Du willst den Text senden und die Übersetzung direkt zurückbekommen.

Genau dafür gibt es den synchronen Localize-Endpunkt: eine Anfrage rein, übersetzte Daten in derselben Struktur zurück. Du sendest Schlüssel-Wert-Inhalte per POST mit Quell- und Zielsprache, der Aufruf blockiert, während deine Engine übersetzt, und die Antwort gibt dir dasselbe Objekt mit übersetzten Werten bei unveränderter Struktur zurück. Es gibt keinen Job, den du verfolgen musst, und keinen zweiten Aufruf.

Die Übersetzung ist kein generischer Modellaufruf. Sie läuft durch die Lokalisierungs-Engine, die du konfiguriert hast – mit ihrem glossary, ihrer Markenstimme, ihren Anweisungen und ihrer sprachspezifischen Modellauswahl – dieselbe Engine, die auch die async API nutzt. Der Unterschied liegt nur in der Form: Async verteilt eine Anfrage auf viele Sprachen und liefert Ergebnisse, sobald sie eintreffen; dieser Aufruf verarbeitet genau ein Sprachpaar und gibt das Ergebnis inline zurück.

Auf dieser Seite

• Anfrage
• Antwort
• Beispiele
• Was bei der Lokalisierung passiert
• Nächste Schritte

Anfrage#

POST /process/localize

Authentifiziere dich mit dem Header X-API-Key. Schlüssel gelten organisationsweit und geben Zugriff auf jede Engine in deiner Organisation – unter Authentifizierung erfährst du, wo du einen Schlüssel erzeugst, und unter Fehler und Statuscodes findest du das vollständige Fehlermodell.

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hello, world!",
    "cta": "Get started"
  },
  "hints": {
    "cta": ["Landing page", "Primary button"]
  }
}

Antwort#

Die Antwort enthält den übersetzten Inhalt in derselben Struktur, die du gesendet hast, plus das Modell, das ihn erzeugt hat, und die Kosten pro Anfrage. Dieselben Schlüssel kommen zurück, in derselben Verschachtelung – dein Code kann die Übersetzung also direkt aus der bereits bekannten Struktur auslesen.

Das Objekt usage schlüsselt die Kosten des Aufrufs auf, damit du Ausgaben ohne separate Abrechnungsabfrage zuordnen kannst:

{
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hallo, Welt!",
    "cta": "Jetzt starten"
  },
  "model": "anthropic/claude-sonnet-4.5",
  "usage": {
    "inputTokens": 2789,
    "outputTokens": 861,
    "cacheReadTokens": 0,
    "cacheWriteTokens": 0,
    "llmCost": 0.02129,
    "localizationCost": 0.001722,
    "cost": 0.023012
  }
}

Beispiele#

Derselbe Aufruf in fünf Sprachen. Der Übersicht halber sendet jedes Beispiel ein flaches Objekt; data akzeptiert aber auch verschachtelte Objekte und Arrays, und die Antwort kommt in genau der Struktur zurück, die du sendest.

const response = await fetch(
  "https://api.lingo.dev/process/localize",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      engineId: "eng_abc123",
      sourceLocale: "en",
      targetLocale: "de",
      data: {
        greeting: "Hello, world!",
        cta: "Get started",
      },
    }),
  }
);

const { data } = await response.json();
// { greeting: "Hallo, Welt!", cta: "Jetzt starten" }

Was bei der Lokalisierung passiert#

Hinter einem einzelnen POST steckt eine ganze Abfolge von Schritten – und es lohnt sich, sie zu kennen. Denn genau sie sorgen dafür, dass das Ergebnis zum Rest deiner lokalisierten Inhalte passt und nicht wie ein einmaliger Modelltreffer wirkt. Wenn eine Anfrage den Endpunkt erreicht, wendet die Engine ihre vollständige Konfiguration der Reihe nach an:

1. Modellauswahl – Wählt das LLM model mit der höchsten Priorität aus, das zum Sprachpaar passt. Sprachspezifische Modelle haben Vorrang vor Wildcard-Modellen (*). Falls das primäre Modell fehlschlägt, wechselt die Engine automatisch zum nächsthöher eingestuften Modell.

2. Markenstimme – Lädt die Markenstimme für die Zielsprache und greift auf die Wildcard-Markenstimme zurück, falls keine sprachspezifische vorhanden ist.

3. Anweisungen – Lädt jede Anweisung, die zur Zielsprache passt, einschließlich Wildcard-Anweisungen.

4. Glossarsuche – Teilt Eingabewerte in durchsuchbare Chunks auf, erzeugt Embeddings und führt eine Vektorähnlichkeitssuche gegen das glossary der Engine aus. Treffer erzwingen exakte Übersetzungen oder markieren Begriffe als nicht übersetzbar, damit sie unverändert durchgereicht werden.

5. Generierung – Sendet den zusammengesetzten Prompt an das ausgewählte Modell und parst und validiert anschließend die JSON-Antwort.

Das ist dieselbe Pipeline aus Engine-Schritten, die die async API pro Job ausführt. Ob du Sync statt Async aufrufst, ändert nur die Art der Auslieferung, nicht die Erzeugung der Übersetzung – ein hier übersetzter String und derselbe String aus einem Async-Job landen also bei denselben Glossarbegriffen und derselben Stimme.

Nächste Schritte#