Dateilokalisierung mit der API automatisieren
Lade eine Quelldatei hoch, starte einen Dokumentauftrag und lade die Übersetzungen in ein separates Ausgabeverzeichnis herunter.
Nutze die Dokument-API, wenn dein Backend die Dateien verwaltet und die Übersetzung mit der eigenen Speicherung abstimmen muss. Dieses Beispiel übersetzt messages/en.json ins Deutsche und Französische. Die CLI führt dieselben Dateioperationen für ein lokales Projekt aus.
Du benötigst Node.js 22 oder neuer, eine Organisation, eine Engine mit konfiguriertem Modell und einen API-Schlüssel mit Übersetzungszugriff. Richte die Übersetzung für diesen ersten Durchlauf ohne menschliche Prüfung ein; füge eine Prüfung hinzu, sobald der gesamte Dateiablauf funktioniert.
Quelldatei vorbereiten #
Erstelle messages/en.json:
{
"title": "Account settings",
"save": "Save changes"
}Setze die folgenden Umgebungsvariablen auf deine eigenen Werte:
export LINGO_API_KEY="YOUR_API_KEY"
export LINGO_ORGANIZATION_ID="YOUR_ORGANIZATION_ID"
export LINGO_ENGINE_ID="YOUR_ENGINE_ID"
export LINGO_REQUEST_ID="account-settings-v1-de-fr"Verwende bei Wiederholungsversuchen für dieselbe Quelle und Konfiguration immer dieselbe Anfrage-ID. Ändere sie, wenn du eine neue Revision übermittelst.
Hochladen, starten und Ergebnisse abrufen #
Speichere dieses Programm als translate-file.mjs:
import { createHash } from "node:crypto";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { setTimeout as delay } from "node:timers/promises";
const origin = "https://api.lingo.dev";
const {
LINGO_API_KEY: apiKey,
LINGO_ORGANIZATION_ID: orgId,
LINGO_ENGINE_ID: engineId,
LINGO_REQUEST_ID: requestId,
} = process.env;
if (!apiKey || !orgId || !engineId || !requestId) throw new Error("Set the four LINGO environment variables");
async function request(path, options = {}) {
const response = await fetch(new URL(path, origin), {
...options,
headers: { "X-API-Key": apiKey, ...options.headers },
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
return response;
}
const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");
let job = await (
await request(`/v2/organizations/${encodeURIComponent(orgId)}/localization/jobs`, {
method: "POST",
headers: { "Content-Type": "application/json", "Idempotency-Key": requestId },
body: JSON.stringify({
engineId,
sourceLocale: "en",
targetLocales: ["de", "fr"],
documents: [{ key: "messages/en.json", format: { type: "json" }, source: address }],
}),
})
).json();
await writeFile("file-job.json", JSON.stringify({ id: job.id, requestId, source: address }, null, 2));
for (const upload of job.uploads) {
await request(upload.uploadUrl, {
method: "PUT",
headers: { "Content-Type": "application/octet-stream" },
body: bytes,
});
}
job = await (
await request(`/v2/localization/jobs/${encodeURIComponent(job.id)}/start`, {
method: "POST",
})
).json();
const deadline = Date.now() + 120_000;
while (["Pending", "Running"].includes(job.status._tag)) {
if (Date.now() >= deadline) throw new Error(`Keep job ${job.id} and check again later`);
await delay(2000);
job = await (await request(`/v2/localization/jobs/${encodeURIComponent(job.id)}`)).json();
}
await mkdir("translated", { recursive: true });
for (const { locale, status } of job.documents[0].targets) {
if (status._tag !== "Completed") {
throw new Error(`Inspect job ${job.id}: ${locale} is ${status._tag}`);
}
const output = await request(status.downloadUrl);
await writeFile(`translated/${locale}.json`, new Uint8Array(await output.arrayBuffer()));
console.log(`Saved translated/${locale}.json`);
}Führe node translate-file.mjs aus und sieh dir anschließend translated/de.json und translated/fr.json an. Beide Dateien sollten die Schlüssel der Quelldatei beibehalten und Inhalte in der jeweiligen Sprache enthalten. Das Programm speichert die Ausgabedateien getrennt von den Anwendungsdateien, damit du vor dem Ersetzen akzeptierter Inhalte eine Prüfung durchführen kannst.
Nach Fehlern fortsetzen, ohne den Auftrag zu duplizieren #
file-job.json speichert die serverseitige Auftragskennung und den Hash der Quelle. Geht eine Antwort auf eine Upload- oder Startanfrage verloren, rufe diesen Auftrag ab, lade die noch ausstehenden Artefakte hoch und wiederhole die Startanfrage. Auch eine erneute Erstellungsanfrage mit dem ursprünglichen Idempotenzschlüssel liefert denselben Auftrag zurück.
Eine Zeitüberschreitung beim Polling bricht die Verarbeitung nicht ab. Rufe den gespeicherten Auftrag weiterhin ab. Erstelle keinen neuen Auftrag, nur weil das lokale Programm nicht mehr wartet.
Dieses Beispiel hält beim ersten unvollständigen Ziel oder bei der ersten fehlgeschlagenen Anfrage an. Bereits gespeicherte Dateien bleiben in translated/. Rufe zum Fortsetzen den in file-job.json gespeicherten Auftrag ab und lade seine fertiggestellten Ziele anhand ihrer downloadUrl-Werte herunter; siehe Auftragsstatus und Ergebnisse. Ein fehlgeschlagener Download erfordert keinen neuen Übersetzungsauftrag.
Inkrementelle Aktualisierungen hinzufügen #
Gib für die nächste Revision previousSource und previousTranslations zusammen mit der neuen Quelladresse an. Bewahre die Bytes aller referenzierten Artefakte auf, bis der Upload erfolgreich abgeschlossen ist. Übernimm akzeptierte menschliche Änderungen in die vorherigen Zieldateien, die du bereitstellst.
Dokumente übersetzen beschreibt die Felder und Regeln zur Wiederverwendung. Vergleiche vor der Veröffentlichung die Quellrevision des Auftrags mit deiner aktuellen Quelle und kontrolliere, ob die Ziele nach der Übermittlung bearbeitet wurden. Einen Übersetzungs-Workflow erstellen erläutert diesen Schritt zur Annahme der Übersetzungen.