SDK-v0-Integrationen warten

Lerne die Hilfsfunktionen von LingoDotDevEngine kennen und bewahre bei der Migration ihr Verhalten bei Eingaben, Ausgaben, Stapelverarbeitung und Abbrüchen.

Eine Anwendung, die LingoDotDevEngine nutzt, verlässt sich womöglich auf mehr als reine Objektübersetzung: Sie kann Anfragen in Blöcke aufteilen, Arrays neu zusammensetzen oder HTML parsen. Bei einer Migration musst du diese Verhaltensweisen gezielt erhalten. Den Import auszutauschen reicht dafür nicht aus.

Diese Referenz bezieht sich auf lingo.dev 0.138.10, dessen lingo.dev/sdk-Eintrag @lingo.dev/_sdk 0.17.3 re-exportiert. Behalte die im Lockfile der Anwendung festgehaltene Version bei, während du die Aufrufstellen durchgehst. Für einen neuen serverseitigen Workflow nutzt du den Leitfaden zur JavaScript-API.

Bestehende Aufrufe zur Objektübersetzung #

Die bisherige serverseitige Form sieht so aus:

ts
import { LingoDotDevEngine } from "lingo.dev/sdk";

const apiKey = process.env.LINGO_API_KEY;
const engineId = process.env.LINGO_ENGINE_ID;
if (!apiKey || !engineId) throw new Error("Configure a key and localization engine ID");

const client = new LingoDotDevEngine({ apiKey, engineId });
const translated = await client.localizeObject(
  { greeting: "Welcome back" },
  { sourceLocale: "en", targetLocale: "es" },
);

Die Hilfsfunktion gibt den übersetzten Datensatz direkt zurück. Zugangsdaten bleiben auf dem Server. Ein Dokumentauftrag durchläuft einen eigenen Lebenszyklus aus Erstellung, Start und Download; die Antwort auf seine Erstellung ist nicht der übersetzte Datensatz dieser Hilfsfunktion.

Konstruktor und Steuerung der Stapelverarbeitung #

OptionBisheriges Verhalten
apiKeyPflichtangabe als Zeichenfolge, vom Konstruktor validiert.
apiUrlÜberschreibt die API-Basis-URL.
engineIdOptionale Auswahl der Lokalisierungs-Engine, die mit der Übersetzung gesendet wird.
batchSizeStandardwert 25, Höchstwert 250.
idealBatchItemSizeStandardwert 250, Höchstwert 2500.
maxRetriesStandardwert 3.
retryDelayMsStandardwert 500 Millisekunden.

Die Optionen zur Stapelverarbeitung legen fest, wie der Client Blöcke bildet – nicht, wie parallel die gesamte Anwendung arbeitet. Die zugehörige Retry-Hilfsfunktion wiederholt Anfragen bei Netzwerk- und 5xx-Fehlern mit exponentiell wachsenden, zufällig gestreuten Wartezeiten. Absichtliche Abbrüche und gewöhnliche 4xx-Antworten wiederholt sie nicht. Andere Vorgänge wie Erkennung und Kontoabfrage laufen über eigene Anfragepfade; geh also nicht davon aus, dass eine einzige Retry-Strategie für alle Methoden gilt.

Eingaben und Rückgabewerte der Hilfsfunktionen #

HilfsfunktionVertrag
localizeObject(object, params, progressCallback?, signal?)Datensatz rein, übersetzter Datensatz raus.
localizeText(text, params, progressCallback?, signal?)Verpackt den Text in ein Feld und gibt die übersetzte Zeichenfolge zurück.
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)Führt für jede Sprache eine Textanfrage aus und gibt die Zeichenfolgen in der angeforderten Reihenfolge der Sprachen zurück.
localizeStringArray(strings, params)Nutzt temporäre Schlüssel und setzt ein Zeichenfolgen-Array neu zusammen; kein öffentlicher Signal-Parameter.
localizeChat(messages, params, progressCallback?, signal?)Übersetzt text in { name, text }-Nachrichten und behält deren Namen bei.
localizeHtml(html, params, progressCallback?, signal?)Parst HTML mit jsdom, übersetzt ausgewählte Inhalte und serialisiert das Ergebnis.
recognizeLocale(text, signal?)Gibt den erkannten Sprachwert zurück.
estimate(items, signal?)Nimmt { targetLocale, sourceChars }-Elemente entgegen und gibt ungefähre Gesamtsummen sowie Kosten pro Sprache zurück.
whoami(signal?)Gibt bei gewöhnlichen erfolglosen Kontoantworten { email, id } oder null zurück; Serverfehler können eine Ausnahme auslösen.

Typische Übersetzungsparameter sind sourceLocale (für die automatische Erkennung auch null), targetLocale, optional fast, Referenzdaten pro Sprache, Hinweis-Arrays pro Schlüssel, filePath und triggerType (cli oder ci). Sprachen werden vor der Verwendung normalisiert. Achte darauf, dass jede Eingabe ihre Bedeutung behält, wenn du sie einem neueren Anfrageschema zuordnest.

Fortschritts-Callbacks melden abgeschlossene Client-Blöcke, einschließlich des erreichten Prozentsatzes sowie der Quell- und verarbeiteten Blöcke. Sie sind keine dauerhaften Benachrichtigungen über Hintergrundaufträge. Ein AbortSignal stoppt die Arbeit des Clients, kann aber nichts rückgängig machen, was der Server bereits zur Verarbeitung angenommen hat.

HTML-Verhalten bewusst erhalten #

Die HTML-Hilfsfunktion übersetzt Textknoten außerhalb von script und style sowie meta.content, img.alt, input.placeholder und a.title. Sie setzt die Dokumentsprache auf die Zielsprache und serialisiert das DOM. Sie übersetzt nicht jedes Attribut und erhält die ursprünglichen Bytes nicht.

Teste diese Hilfsfunktion in der echten Server-Laufzeitumgebung – einschließlich der Auflösung ihres dynamischen jsdom-Imports. Vergleiche Links, strukturelles Markup, ausgewählte Attribute und die serialisierte Ausgabe, bevor du einen HTML-Aufruf auf eine andere Transformation umstellst. Eine strukturierte JSON-Anfrage allein übernimmt diese HTML-Schritte nicht.

ReplexicaEngine und LingoEngine erweitern LingoDotDevEngine als Kompatibilitäts-Aliase und geben Deprecation-Warnungen aus. Wer eine Alias-Warnung beseitigt, ändert nur einen Namen – die Migration des Verhaltens ist damit noch nicht erledigt.

Eine Anwendung auf Dokumentaufträge umstellen #

Für eine neue Integration nutzt du den Lebenszyklus von API-Aufträgen. Lege Objektinhalte in einem Inline-JSON-Dokument ab, starte den Auftrag und lade jedes fertige Ziel herunter. Bewahre die Auftrags-ID zusammen mit der Quellrevision auf, bis die Anwendung das Ergebnis übernommen hat.

Erhalte jedes Anwendungsverhalten, das derzeit vom Verpacken von Text, der Array-Reihenfolge, dem HTML-Parsing, der Stapelverarbeitung oder von Fortschritts-Callbacks abhängt. Für die Dateiübersetzung kannst du das passende Dokumentformat verwenden. Ein neuer Transportweg bildet clientseitige Transformationen oder Wiederholungsversuche nicht automatisch nach.

Vergleiche die resultierenden Daten und die Fehlerbehandlung, bevor du die Speicherung der Anwendung auf den neuen Ablauf umstellst. Der Workflow-Leitfaden erklärt Teilergebnisse und Abschlüsse in abweichender Reihenfolge.