Контент — на одном языке, а пользователи читают на разных. API создан, чтобы устранить этот разрыв без лишних усилий: отправляете текст — получаете перевод, и каждый перевод проходит через движок локализации, который вы настроили один раз. Движок применяет глоссарий, тональность бренда, правила и выбор модели для каждой локали при каждом вызове — результат звучит именно так, как решила ваша Team, а не так, как решила за вас универсальная модель.
Остаётся решить только одно: какой объём вы хотите переводить за раз. Можно перевести одну локаль одним запросом и сразу получить результат в ответе. А можно передать платформе сразу несколько локалей и позволить ей переводить каждую как отдельную фоновую задачу, пока ваше приложение остаётся отзывчивым. На этой странице вы найдёте базовый URL, разницу между этими двумя вариантами и следующие шаги.
Что предполагает это API
Это справочник по программному переводу. Предполагается, что вы уже решили заниматься локализацией из собственного кода или пайплайна, а не через панель управления, и что у вас есть API-ключ. Впервые на платформе? Тогда в первую очередь стоит разобраться с концепцией движка локализации — всё здесь работает через него.
На этой странице
- Базовый URL
- Два способа перевода
- Асинхронно: много локалей как задачи
- Синхронно: один запрос, один ответ
- Следующие шаги
Базовый URL#
Все REST-эндпоинты в этом справочнике находятся на одном хосте:
https://api.lingo.devКаждый запрос также должен содержать заголовок X-API-Key. Ключ привязан к организации и показывается только один раз при создании; полные правила его передачи описаны в разделе Authentication, а то, что возвращается при отклонении запроса, — в разделе Errors and status codes.
Два способа перевода#
В основе обоих режимов — один и тот же движок, один и тот же глоссарий и одна и та же тональность бренда. Отличается только то, кто берёт на себя ожидание.
Синхронный вызов переводит одну пару локалей и возвращает переведённые данные прямо в ответе. Это более простой вариант: один запрос, один ответ и никакой дополнительной инфраструктуры на вашей стороне. Он подходит, когда вам нужна одна локаль и вы готовы дождаться одного запроса-ответа.
Но контент редко выходит только для одной локали. Учебный модуль может охватывать 14 языков, а запись в CMS — расходиться по всем рынкам, где вы продаёте. Если отправлять по одному синхронному вызову на каждую локаль, вам придётся обрабатывать 14 циклов запрос-ответ и продумывать логику повторных попыток, если один из них завершится ошибкой. А если ждать один синхронный вызов для всех сразу, вы упрётесь в самую медленную локаль. Поэтому у API есть и асинхронный режим: вы один раз отправляете контент через POST с целевыми локалями, сразу получаете 202, а платформа переводит каждую локаль как независимую фоновую задачу, беря на себя повторы и изоляцию сбоев, пока ваше приложение остаётся отзывчивым.
Выбирайте async, когда задача слишком большая, слишком медленная или включает слишком много локалей, чтобы блокировать выполнение. Выбирайте sync, когда всё, что вам нужно, — это одна пара локалей в одном ответе. Ниже сначала идут страницы про async, потому что там больше возможностей, но ни один из вариантов не является «основным» API — это просто две формы одного и того же движка.
Асинхронно: много локалей как задачи#
Один запрос, все локали, результаты по мере готовности. Асинхронный API принимает одну отправку, создаёт отдельную задачу для каждой целевой локали и доставляет каждый результат сразу после завершения — через webhook или WebSocket — без блокировки вашего приложения.
Синхронно: один запрос, один ответ#
Когда вам нужна одна пара локалей и вы можете дождаться ответа, вызовите sync-эндпоинт и получите результат прямо в ответе — без webhook-эндпоинта и без polling.
Следующие шаги#
Какой бы режим вы ни выбрали, движок за ним можно точно настроить под свои задачи. Сначала создайте ключ, а затем определите, что движок будет делать при каждом вызове: какую модель выбирать для каждой локали и какие термины переводить строго заданным образом.
