Die API mit JavaScript aufrufen

JSON von einem Node.js-Server aus übersetzen, auf das Ergebnis warten und es in einer Datei speichern.

Nutze das native fetch, um strukturierte Inhalte von deinem Server aus zu übersetzen. In diesem Beispiel wird eine englische Überschrift für die Kontoeinstellungen ins Französische übersetzt und als settings.fr.json gespeichert. Du benötigst Node.js 22 oder neuer und eine Engine, für die ein Übersetzungsmodell konfiguriert ist.

Bewahre Zugangsdaten auf dem Server auf. Die React-Laufzeit rendert Kataloge ohne API-Schlüssel.

Die Anfrage konfigurieren #

Erstelle einen API-Schlüssel mit Übersetzungszugriff auf deine Engine und ermittle die Organisations- und Engine-IDs. Verwende für dieses Beispiel eine Engine, bei der die menschliche Prüfung deaktiviert ist.

sh
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="settings-v1-fr"

Verwende denselben Wert für LINGO_REQUEST_ID, wenn du diese Übermittlung erneut versuchst. Wähle einen neuen Wert, wenn sich die Quelle, die Sprachen oder andere Anfrageoptionen ändern.

Übersetzen und das Ergebnis speichern #

Speichere dies als translate.mjs:

js
import { writeFile } from "node:fs/promises";
import { setTimeout as delay } from "node:timers/promises";

const apiKey = process.env.LINGO_API_KEY;
const orgId = process.env.LINGO_ORGANIZATION_ID;
const engineId = process.env.LINGO_ENGINE_ID;
const requestId = process.env.LINGO_REQUEST_ID;
if (!apiKey || !orgId || !engineId || !requestId) {
  throw new Error("Set LINGO_API_KEY, LINGO_ORGANIZATION_ID, LINGO_ENGINE_ID, and LINGO_REQUEST_ID");
}

async function request(path, options = {}) {
  const response = await fetch(new URL(path, "https://api.lingo.dev"), {
    ...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;
}

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: ["fr"],
      documents: [
        {
          key: "settings.json",
          format: { type: "json" },
          source: { content: { heading: "Account settings" } },
        },
      ],
    }),
  })
).json();
await writeFile("job.json", JSON.stringify({ id: job.id, requestId }, null, 2));
if (job.uploads.length) throw new Error("Upload the missing artifacts before starting");

const jobPath = `/v2/localization/jobs/${encodeURIComponent(job.id)}`;
job = await (await request(`${jobPath}/start`, { method: "POST" })).json();

const deadline = Date.now() + 120_000;
while (["Pending", "Running"].includes(job.status._tag)) {
  if (Date.now() >= deadline) throw new Error(`Still waiting for ${job.id}; keep job.json and check again later`);
  await delay(2000);
  job = await (await request(jobPath)).json();
}

const target = job.documents
  .find((document) => document.key === "settings.json")
  ?.targets.find((item) => item.locale === "fr");
if (target?.status._tag !== "Completed") {
  throw new Error(`Translation did not complete: ${JSON.stringify(job.status)}`);
}
const translated = await (await request(target.status.downloadUrl)).json();
if (typeof translated.heading !== "string") throw new Error("The result is missing its heading");
await writeFile("settings.fr.json", JSON.stringify(translated, null, 2) + "\n");
console.log("Saved settings.fr.json");

Führe node translate.mjs aus, öffne anschließend settings.fr.json und sieh dir die französische Überschrift an. Das Programm speichert die Auftrags-ID vor Beginn der Verarbeitung und lädt das Ergebnis erst herunter, wenn die Verarbeitung für die Zielsprache abgeschlossen ist.

Die Hilfsfunktion für Anfragen kontrolliert den HTTP-Status, bevor sie die Antwort liest. Nutze bei einem HTTP-Fehler den Status und die Problemdetails, um zu entscheiden, was du korrigieren musst. Ein Netzwerkfehler oder eine Zeitüberschreitung kann auch dann auftreten, wenn der Server den Auftrag bereits angenommen hat.

Nach einer Unterbrechung fortfahren #

Lies die ID aus job.json und rufe den Auftrag ab, um seinen Status weiter abzufragen. Wenn die Antwort auf die Erstellungsanfrage verloren gegangen ist, bevor die Datei gespeichert wurde, wiederhole dieselbe Anfrage mit demselben Idempotenzschlüssel. Wenn du /start erneut ausführst, wird derselbe Auftrag fortgesetzt. Eine Zeitüberschreitung beendet das Warten des Programms, ohne die Verarbeitung auf dem Server abzubrechen.

Wenn deine Anwendung viele Übermittlungen verarbeitet oder auf eine menschliche Prüfung wartet, erstelle einen Übersetzungs-Workflow, der Auftrags-IDs und Quellrevisionen speichert und Ergebnisse in einem Hintergrundprozess abruft. Unter Dateien übersetzen erfährst du mehr über das Hochladen von Artefakten und Teilergebnisse für mehrere Sprachen.