Translation API

Die Lingo.dev-Lokalisierungs-API übersetzt Schlüssel-Wert-Daten über eine konfigurierte Lokalisierungs-Engine. Ein HTTP-Aufruf – Ihre Strings gehen rein, übersetzte Strings kommen zurück, wobei Glossarregeln, Markenstimme und Modellauswahl automatisch angewendet werden.

Wann Sie die API verwenden sollten#

Verwenden Sie die Lokalisierungs-API, wenn Übersetzungen zur Laufzeit oder in einem Backend-Service stattfinden – nicht beim Build.

Anwendungsfall	Beispiel
Dynamische Inhalte	Übersetzen Sie Kursbeschreibungen, Lektionstitel oder Quizfragen, die in einer Datenbank gespeichert sind
Nutzergenerierte Inhalte	Übersetzen Sie Bewertungen, Kommentare oder Forumsbeiträge bei Bedarf
API-Antworten	Geben Sie lokalisierte Inhalte aus Ihrem Backend passend zur Sprache des Benutzers zurück
Benachrichtigungen	Übersetzen Sie E-Mail-Betreffzeilen, Push-Benachrichtigungen oder In-App-Nachrichten vor dem Versand

Build-Zeit vs. Laufzeit

Wenn Ihre Inhalte in statischen Dateien (JSON, Markdown, .strings) liegen, sind die CLI oder die CI/CD-Integration die bessere Wahl. Die API ist für die Lokalisierung von Inhalten im Backend konzipiert.

Voraussetzungen#

Eine Lokalisierungs-Engine erstellen

Jeder API-Aufruf läuft über eine Lokalisierungs-Engine – die Konfiguration, die festlegt, welches LLM-Modell, Glossar, welche Markenstimme und welche Anweisungen gelten. Erstellen Sie sie im Lingo.dev-Dashboard.

Einen API-Schlüssel generieren

API-Anfragen werden mit einem X-API-Key-Header authentifiziert. Generieren Sie einen Schlüssel im Bereich API Keys. Schlüssel werden bei der Erstellung nur einmal angezeigt – bewahren Sie Ihren sicher auf.

Inhalte lokalisieren#

Senden Sie eine POST-Anfrage an den Localize-Endpunkt – mit Ihrer Quellsprache, Zielsprache und den Schlüssel-Wert-Daten. Das vollständige Anfrage-/Antwortschema ist in der API-Referenz dokumentiert.

Dieses Beispiel übersetzt einen Absatz aus einem JavaScript-Kurs ins Spanische:

javascript

const content = {
  intro: "JavaScript is a programming language that powers the interactive elements of most websites. When you click a button, submit a form, or see content update without the page reloading, JavaScript is making that happen.",
};

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: "es",
    data: content,
  }),
});

const { data } = await response.json();
// {
//   intro: "JavaScript es un lenguaje de programacion que impulsa los elementos interactivos de la mayoria de los sitios web. Cuando haces clic en un boton, envias un formulario o ves contenido actualizarse sin que la pagina se recargue, JavaScript lo esta haciendo posible."
// }

Schlüssel bleiben erhalten: Sie senden intro und erhalten intro zurück. Die Engine übersetzt nur die Werte.

Schlüssel strukturieren#

Das data-Objekt ist flach – jeder Schlüssel verweist auf genau einen String. Strukturieren Sie Ihre Schlüssel so, dass sie semantischen Kontext mitgeben:

javascript

const content = {
  "variables.intro": "Variables are containers for storing data values. In JavaScript, you declare them with let, const, or var.",
  "variables.example": "Use const for values that never change, and let for values that do.",
  "variables.exercise": "Declare a variable called age and assign it your age as a number.",
};

Semantisch gruppierte Schlüssel helfen der Lokalisierungs-Engine, stimmigere Übersetzungen zu erzeugen. Die Engine versteht alle Schlüssel innerhalb einer Anfrage als zusammenhängenden Kontext – variables.intro und variables.example werden konsistenter übersetzt, wenn sie gemeinsam statt getrennt gesendet werden.

Technische Begriffe

Begriffe wie "const" oder "let" sind Programmierjargon und sollten nicht übersetzt werden. Verwenden Sie ein Glossar, um Begriffe als nicht übersetzbar zu markieren oder sie auf sprachspezifische Entsprechungen abzubilden. Wenn Sie einen KI-Coding-Assistenten wie Claude Code oder Cursor verwenden, kann das Localization MCP dabei helfen, Glossarregeln als Teil Ihres Entwicklungs-Workflows zu konfigurieren.

Beim Speichern lokalisieren#

Typischerweise übersetzen Sie Inhalte dann, wenn sie erstellt oder aktualisiert werden – nicht erst beim Abrufen. So liegen die übersetzten Inhalte bereits in der Datenbank vor, wenn ein Benutzer sie anfordert.

javascript

app.post("/api/lessons", async (req, res) => {
  const lesson = await db.lessons.create(req.body);

  const content = {
    intro: lesson.intro,
    example: lesson.example,
    exercise: lesson.exercise,
  };

  const targetLocales = ["es", "fr", "de", "ja"];

  const translations = await Promise.all(
    targetLocales.map(async (targetLocale) => {
      const response = await fetch("https://api.lingo.dev/process/localize", {
        method: "POST",
        headers: {
          "X-API-Key": process.env.LINGODOTDEV_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          sourceLocale: "en",
          targetLocale,
          data: content,
        }),
      });

      const { data } = await response.json();
      return { locale: targetLocale, data };
    })
  );

  await db.lessonTranslations.insertMany(
    translations.map((t) => ({
      lessonId: lesson.id,
      locale: t.locale,
      ...t.data,
    }))
  );

  res.json(lesson);
});

Das Abrufen lokalisierter Inhalte wird dadurch zu einer einfachen Datenbankabfrage – ein API-Aufruf zur Lesezeit ist nicht mehr nötig:

javascript

app.get("/api/lessons/:id", async (req, res) => {
  const locale = req.query.locale || "en";

  if (locale === "en") {
    const lesson = await db.lessons.findById(req.params.id);
    return res.json(lesson);
  }

  const translation = await db.lessonTranslations.findOne({
    lessonId: req.params.id,
    locale,
  });

  res.json(translation);
});

Nächste Schritte#

API-Referenz

Vollständiges Anfrage-/Antwortschema für die Endpunkte localize und recognize

Glossare

Legen Sie fest, welche technischen Begriffe übersetzt werden und welche unverändert bleiben

Markenstimmen

Legen Sie Formalität und Tonalität pro Zielsprache fest

CI/CD-Workflows

Automatisieren Sie die Lokalisierung statischer Inhalte beim Build

Wann Sie die API verwenden sollten#

Verwenden Sie die Lokalisierungs-API, wenn Übersetzungen zur Laufzeit oder in einem Backend-Service stattfinden – nicht beim Build.

Anwendungsfall	Beispiel
Dynamische Inhalte	Übersetzen Sie Kursbeschreibungen, Lektionstitel oder Quizfragen, die in einer Datenbank gespeichert sind
Nutzergenerierte Inhalte	Übersetzen Sie Bewertungen, Kommentare oder Forumsbeiträge bei Bedarf
API-Antworten	Geben Sie lokalisierte Inhalte aus Ihrem Backend passend zur Sprache des Benutzers zurück
Benachrichtigungen	Übersetzen Sie E-Mail-Betreffzeilen, Push-Benachrichtigungen oder In-App-Nachrichten vor dem Versand

Build-Zeit vs. Laufzeit

Voraussetzungen#

Eine Lokalisierungs-Engine erstellen

Einen API-Schlüssel generieren

Inhalte lokalisieren#

Dieses Beispiel übersetzt einen Absatz aus einem JavaScript-Kurs ins Spanische:

javascript

const content = {
  intro: "JavaScript is a programming language that powers the interactive elements of most websites. When you click a button, submit a form, or see content update without the page reloading, JavaScript is making that happen.",
};

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: "es",
    data: content,
  }),
});

const { data } = await response.json();
// {
//   intro: "JavaScript es un lenguaje de programacion que impulsa los elementos interactivos de la mayoria de los sitios web. Cuando haces clic en un boton, envias un formulario o ves contenido actualizarse sin que la pagina se recargue, JavaScript lo esta haciendo posible."
// }

Schlüssel bleiben erhalten: Sie senden intro und erhalten intro zurück. Die Engine übersetzt nur die Werte.

Schlüssel strukturieren#

Das data-Objekt ist flach – jeder Schlüssel verweist auf genau einen String. Strukturieren Sie Ihre Schlüssel so, dass sie semantischen Kontext mitgeben:

javascript

const content = {
  "variables.intro": "Variables are containers for storing data values. In JavaScript, you declare them with let, const, or var.",
  "variables.example": "Use const for values that never change, and let for values that do.",
  "variables.exercise": "Declare a variable called age and assign it your age as a number.",
};

Technische Begriffe

Beim Speichern lokalisieren#

javascript

app.post("/api/lessons", async (req, res) => {
  const lesson = await db.lessons.create(req.body);

  const content = {
    intro: lesson.intro,
    example: lesson.example,
    exercise: lesson.exercise,
  };

  const targetLocales = ["es", "fr", "de", "ja"];

  const translations = await Promise.all(
    targetLocales.map(async (targetLocale) => {
      const response = await fetch("https://api.lingo.dev/process/localize", {
        method: "POST",
        headers: {
          "X-API-Key": process.env.LINGODOTDEV_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          sourceLocale: "en",
          targetLocale,
          data: content,
        }),
      });

      const { data } = await response.json();
      return { locale: targetLocale, data };
    })
  );

  await db.lessonTranslations.insertMany(
    translations.map((t) => ({
      lessonId: lesson.id,
      locale: t.locale,
      ...t.data,
    }))
  );

  res.json(lesson);
});

Das Abrufen lokalisierter Inhalte wird dadurch zu einer einfachen Datenbankabfrage – ein API-Aufruf zur Lesezeit ist nicht mehr nötig:

javascript

app.get("/api/lessons/:id", async (req, res) => {
  const locale = req.query.locale || "en";

  if (locale === "en") {
    const lesson = await db.lessons.findById(req.params.id);
    return res.json(lesson);
  }

  const translation = await db.lessonTranslations.findOne({
    lessonId: req.params.id,
    locale,
  });

  res.json(translation);
});

Nächste Schritte#

API-Referenz

Vollständiges Anfrage-/Antwortschema für die Endpunkte localize und recognize

Glossare

Legen Sie fest, welche technischen Begriffe übersetzt werden und welche unverändert bleiben

Markenstimmen

Legen Sie Formalität und Tonalität pro Zielsprache fest

CI/CD-Workflows

Automatisieren Sie die Lokalisierung statischer Inhalte beim Build