Translation API

Lingo.dev lokalizační API překládá data ve formátu klíč–hodnota přes nakonfigurovaný lokalizační engine. Jedno HTTP volání – pošlete své řetězce a zpátky dostanete přeložené, přičemž pravidla glosáře, hlas značky i výběr modelu se použijí automaticky.

Kdy použít API#

Lokalizační API použijte, když překlady probíhají za běhu aplikace nebo v backendové službě – ne při buildu.

Případ použití	Příklad
Dynamický obsah	Překlad popisů kurzů, názvů lekcí nebo kvízových otázek uložených v databázi
Obsah vytvářený uživateli	Překlad recenzí, komentářů nebo příspěvků ve fóru na vyžádání
Odpovědi API	Vrácení lokalizovaného obsahu z backendu podle jazyka uživatele
Notifikace	Překlad předmětů e-mailů, push notifikací nebo zpráv v aplikaci před odesláním

Build-time vs runtime

Pokud váš obsah žije ve statických souborech (JSON, Markdown, .strings), lepší volbou je CLI nebo CI/CD integrace. API je navržené pro lokalizaci obsahu na backendu.

Požadavky#

Vytvořte lokalizační engine

Každé API volání prochází přes lokalizační engine – konfiguraci, která určuje, jaký LLM model, glosář, hlas značky a instrukce se použijí. Vytvoříte ho v dashboardu Lingo.dev.

Vygenerujte API klíč

API požadavky se ověřují pomocí hlavičky X-API-Key. Klíč vygenerujete v sekci API Keys. Klíče se při vytvoření zobrazí jen jednou – proto si ten svůj bezpečně uložte.

Lokalizace obsahu#

Odešlete požadavek POST na endpoint localize se zdrojovým jazykem, cílovým jazykem a daty ve formátu klíč–hodnota. Kompletní schéma request/response najdete v API referenci.

Tento příklad překládá odstavec z kurzu JavaScriptu do španělštiny:

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."
// }

Klíče zůstávají zachované: odešlete intro a zpět dostanete intro. Engine překládá pouze hodnoty.

Jak strukturovat klíče#

Objekt data je plochý – každý klíč odpovídá jednomu řetězci. Strukturu klíčů navrhněte tak, aby nesla sémantický kontext:

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.",
};

Sémanticky seskupené klíče pomáhají lokalizačnímu engine vytvářet konzistentnější překlady. Engine vnímá všechny klíče v jednom požadavku jako související kontext – variables.intro a variables.example se přeloží konzistentněji, když je odešlete společně, než když je pošlete zvlášť.

Technické termíny

Výrazy jako "const" nebo "let" jsou součástí programátorské terminologie a neměly by se překládat. Pomocí glosáře můžete označit termíny jako nepřeložitelné nebo je mapovat na ekvivalenty specifické pro daný jazyk. Pokud používáte AI asistenta pro programování, jako je Claude Code nebo Cursor, Localization MCP vám pomůže nastavit pravidla glosáře jako součást vývojového workflow.

Lokalizace při uložení#

Běžný postup je překládat obsah při vytvoření nebo aktualizaci – ne až ve chvíli, kdy se čte. Díky tomu už je přeložený obsah v databázi ve chvíli, kdy si ho uživatel vyžádá.

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);
});

Načítání lokalizovaného obsahu se pak zredukuje na jednoduchý dotaz do databáze – při čtení už není potřeba žádné API volání:

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);
});

Další kroky#

API Reference

Kompletní schéma request/response pro endpointy localize a recognize

Glosáře

Určete, které technické termíny se mají překládat a které mají zůstat beze změny

Hlasy značky

Nastavte formálnost a tón pro každý cílový jazyk

CI/CD Workflows

Automatizujte lokalizaci statického obsahu při buildu

Kdy použít API#

Lokalizační API použijte, když překlady probíhají za běhu aplikace nebo v backendové službě – ne při buildu.

Případ použití	Příklad
Dynamický obsah	Překlad popisů kurzů, názvů lekcí nebo kvízových otázek uložených v databázi
Obsah vytvářený uživateli	Překlad recenzí, komentářů nebo příspěvků ve fóru na vyžádání
Odpovědi API	Vrácení lokalizovaného obsahu z backendu podle jazyka uživatele
Notifikace	Překlad předmětů e-mailů, push notifikací nebo zpráv v aplikaci před odesláním

Build-time vs runtime

Pokud váš obsah žije ve statických souborech (JSON, Markdown, .strings), lepší volbou je CLI nebo CI/CD integrace. API je navržené pro lokalizaci obsahu na backendu.

Požadavky#

Vytvořte lokalizační engine

Každé API volání prochází přes lokalizační engine – konfiguraci, která určuje, jaký LLM model, glosář, hlas značky a instrukce se použijí. Vytvoříte ho v dashboardu Lingo.dev.

Vygenerujte API klíč

API požadavky se ověřují pomocí hlavičky X-API-Key. Klíč vygenerujete v sekci API Keys. Klíče se při vytvoření zobrazí jen jednou – proto si ten svůj bezpečně uložte.

Lokalizace obsahu#

Odešlete požadavek POST na endpoint localize se zdrojovým jazykem, cílovým jazykem a daty ve formátu klíč–hodnota. Kompletní schéma request/response najdete v API referenci.

Tento příklad překládá odstavec z kurzu JavaScriptu do španělštiny:

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."
// }

Klíče zůstávají zachované: odešlete intro a zpět dostanete intro. Engine překládá pouze hodnoty.

Jak strukturovat klíče#

Objekt data je plochý – každý klíč odpovídá jednomu řetězci. Strukturu klíčů navrhněte tak, aby nesla sémantický kontext:

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.",
};

Technické termíny

Lokalizace při uložení#

Běžný postup je překládat obsah při vytvoření nebo aktualizaci – ne až ve chvíli, kdy se čte. Díky tomu už je přeložený obsah v databázi ve chvíli, kdy si ho uživatel vyžádá.

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);
});

Načítání lokalizovaného obsahu se pak zredukuje na jednoduchý dotaz do databáze – při čtení už není potřeba žádné API volání:

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);
});

Další kroky#

API Reference

Kompletní schéma request/response pro endpointy localize a recognize

Glosáře

Určete, které technické termíny se mají překládat a které mají zůstat beze změny

Hlasy značky

Nastavte formálnost a tón pro každý cílový jazyk

CI/CD Workflows

Automatizujte lokalizaci statického obsahu při buildu