API локализации

API локализации Lingo.dev переводит данные в формате ключ-значение через настроенный движок локализации. Один HTTP-запрос — и на входе ваши строки, а на выходе уже переведённые строки с автоматически применёнными правилами глоссария, тональностью бренда и выбранной моделью.

Когда использовать API#

Используйте API локализации, когда переводы выполняются во время выполнения или в бэкенд-сервисе, а не на этапе сборки.

Сценарий	Пример
Динамический контент	Переводите описания курсов, названия уроков или вопросы викторин, которые хранятся в базе данных
Пользовательский контент	Переводите отзывы, комментарии или сообщения на форуме по запросу
Ответы API	Возвращайте локализованный контент из бэкенда в зависимости от локали пользователя
Уведомления	Переводите темы писем, push-уведомления или сообщения в приложении перед отправкой

Сборка или runtime

Если ваш контент хранится в статических файлах (JSON, Markdown, .strings), лучше подойдут CLI или интеграция CI/CD. API создан для локализации контента на бэкенде.

Что понадобится#

Создайте движок локализации

Каждый вызов API проходит через движок локализации — конфигурацию, которая определяет, какая LLM-модель, глоссарий, тональность бренда и инструкции будут применяться. Создайте его в панели управления Lingo.dev.

Сгенерируйте API-ключ

Запросы к API аутентифицируются через заголовок X-API-Key. Сгенерируйте ключ в разделе API Keys. При создании ключ показывается только один раз — сохраните его в надёжном месте.

Локализация контента#

Отправьте запрос POST в endpoint localize, указав исходную локаль, целевую локаль и данные в формате ключ-значение. Полная схема запроса и ответа описана в справочнике API.

В этом примере абзац из курса по JavaScript переводится на испанский:

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

Ключи сохраняются: вы отправляете intro и получаете обратно intro. Движок переводит только значения.

Как структурировать ключи#

Объект data — плоский: каждый ключ соответствует одной строке. Структурируйте ключи так, чтобы они передавали семантический контекст:

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

Семантически сгруппированные ключи помогают движку локализации выдавать более связные переводы. Движок воспринимает все ключи в одном запросе как общий контекст — variables.intro и variables.example переводятся более последовательно, если отправлять их вместе, а не по отдельности.

Технические термины

Такие термины, как "const" или "let", относятся к языку программирования и не должны переводиться. Используйте глоссарий, чтобы пометить термины как непереводимые, или сопоставить их с эквивалентами для конкретной локали. Если вы используете AI-помощника для программирования, например Claude Code или Cursor, Localization MCP поможет настроить правила глоссария как часть вашего рабочего процесса разработки.

Локализация при сохранении#

Обычно контент переводят в момент создания или обновления, а не при чтении. Тогда к моменту запроса пользователя переведённый контент уже будет в базе данных.

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

После этого получение локализованного контента сводится к обычному запросу к базе данных — вызывать API при чтении не нужно:

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

Что дальше#

Справочник API

Полная схема запросов и ответов для endpoint-ов localize и recognize

Глоссарии

Управляйте тем, какие технические термины переводить, а какие оставлять без изменений

Тональности бренда

Настройте формальность и тон для каждой целевой локали

Рабочие процессы CI/CD

Автоматизируйте локализацию статического контента на этапе сборки

Когда использовать API#

Сценарий	Пример
Динамический контент	Переводите описания курсов, названия уроков или вопросы викторин, которые хранятся в базе данных
Пользовательский контент	Переводите отзывы, комментарии или сообщения на форуме по запросу
Ответы API	Возвращайте локализованный контент из бэкенда в зависимости от локали пользователя
Уведомления	Переводите темы писем, push-уведомления или сообщения в приложении перед отправкой

Сборка или runtime

Что понадобится#

Создайте движок локализации

Сгенерируйте API-ключ

Локализация контента#

В этом примере абзац из курса по JavaScript переводится на испанский:

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

Ключи сохраняются: вы отправляете intro и получаете обратно intro. Движок переводит только значения.

Как структурировать ключи#

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

Технические термины

Локализация при сохранении#

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

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

Что дальше#

Справочник API

Полная схема запросов и ответов для endpoint-ов localize и recognize

Глоссарии

Управляйте тем, какие технические термины переводить, а какие оставлять без изменений

Тональности бренда

Настройте формальность и тон для каждой целевой локали

Рабочие процессы CI/CD

Автоматизируйте локализацию статического контента на этапе сборки