Локализация

У вас есть строка или небольшой объект со строками, который нужно перевести на другой язык прямо сейчас: подпись поля формы, уведомление, короткий фрагмент UI-текста, которого ждёт пользователь. Вам не хочется поднимать endpoint с webhook или опрашивать задачу ради одного ответа. Вам нужно отправить текст и сразу получить перевод.

Именно для этого нужен синхронный endpoint Localize: один запрос — и переведённые данные возвращаются в той же структуре. Вы отправляете контент в формате ключ-значение с исходной и целевой локалью, запрос блокируется, пока ваш движок выполняет перевод, а в ответе приходит тот же объект — с переведёнными значениями и без изменений в структуре. Не нужно отслеживать задачу и делать второй запрос.

Это не просто вызов общей модели. Перевод проходит через настроенный вами движок локализации: его glossary, тональность бренда, instructions и выбор модели для каждой локали — тот же самый движок, который использует async API. Разница только в формате: async разворачивает один запрос на много локалей и возвращает результаты по мере готовности, а этот вызов работает с одной парой локалей и возвращает результат inline.

На этой странице

• Запрос
• Ответ
• Примеры
• Что происходит во время локализации
• Следующие шаги

Запрос#

POST /process/localize

Для аутентификации используйте заголовок X-API-Key. Ключи привязаны к организации и дают доступ ко всем движкам в её рамках — см. Authentication, чтобы узнать, где его сгенерировать, и Errors and status codes для полной модели ошибок.

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hello, world!",
    "cta": "Get started"
  },
  "hints": {
    "cta": ["Landing page", "Primary button"]
  }
}

Ответ#

В ответе вы получаете переведённый контент в той же структуре, что и отправили, а также модель, которая выполнила перевод, и стоимость запроса. Возвращаются те же ключи и та же вложенность — ваш код может извлечь перевод из уже знакомой ему структуры.

Объект usage детализирует стоимость вызова, чтобы вы могли учитывать расходы без отдельного обращения к биллингу:

{
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hallo, Welt!",
    "cta": "Jetzt starten"
  },
  "model": "anthropic/claude-sonnet-4.5",
  "usage": {
    "inputTokens": 2789,
    "outputTokens": 861,
    "cacheReadTokens": 0,
    "cacheWriteTokens": 0,
    "llmCost": 0.02129,
    "localizationCost": 0.001722,
    "cost": 0.023012
  }
}

Примеры#

Один и тот же вызов на пяти языках. Для наглядности в каждом примере используется плоский объект; data также принимает вложенные объекты и массивы, а ответ возвращается в той же структуре, которую вы отправили.

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: "de",
      data: {
        greeting: "Hello, world!",
        cta: "Get started",
      },
    }),
  }
);

const { data } = await response.json();
// { greeting: "Hallo, Welt!", cta: "Jetzt starten" }

Что происходит во время локализации#

За одним POST скрывается целая последовательность шагов, и полезно понимать, каких именно, — потому что именно они делают результат согласованным с остальным локализованным контентом, а не превращают его в разовую догадку модели. Когда запрос попадает в endpoint, движок по порядку применяет всю свою конфигурацию:

1. Выбор модели — выбирается LLM model с наивысшим приоритетом для этой пары локалей. Модели, заданные для конкретных локалей, имеют приоритет над wildcard-моделями (*). Если основная модель не срабатывает, движок автоматически переходит к следующей по рангу.

2. Тональность бренда — загружается тональность бренда для целевой локали, а если её нет — используется wildcard-версия.

3. Instructions — загружаются все instruction, подходящие для целевой локали, включая wildcard-instructions.

4. Поиск по глоссарию — входные значения разбиваются на пригодные для поиска чанки, для них создаются эмбеддинги, после чего выполняется поиск по векторному сходству в glossary движка. Найденные термины закрепляют точные переводы или помечают термины как непереводимые, чтобы они проходили без изменений.

5. Генерация — составленный prompt отправляется в выбранную модель, после чего JSON-ответ разбирается и проходит валидацию.

Это тот же набор шагов движка, который async API выполняет для каждой задачи. Выбор sync вместо async меняет способ доставки результата, а не сам процесс перевода, — поэтому строка, переведённая здесь, и та же строка, переведённая в асинхронной задаче, будут опираться на одни и те же термины глоссария и ту же тональность.

Следующие шаги#