Контент меняется — и теперь его нужно доставить во все локали, с которыми вы работаете. В учебный модуль добавили новый урок. Запись в CMS сохранена. Описание товара обновлено. Перевод должен уйти на немецкий, французский, японский и ещё дюжину языков — и ваше приложение не должно блокироваться, пока всё это происходит.
Асинхронный API локализации создан именно для таких ситуаций: один запрос, все локали, результаты по мере готовности. Вы один раз отправляете POST с контентом и целевыми локалями, сразу получаете 202, а платформа переводит каждую локаль как отдельную фоновую задачу. При этом вы сохраняете свой глоссарий, тональность бренда и конфигурацию модели — тот же движок, который использует Синхронный API — и больше не берёте на себя повторы запросов.
На этой странице
Проблема#
Образовательным платформам, системам управления контентом и e-learning-инструментам часто нужно переводить контент на десятки языков сразу после создания или обновления. Синхронный API локализации с этим справляется, но в масштабе заставляет идти на компромисс.
Представьте учебный модуль на английском, который нужно доставить учащимся на 14 языках. С синхронным API у вас есть два варианта, и оба связаны с издержками:
Отправить 14 параллельных вызовов — по одному запросу на каждую целевую локаль, каждый с одинаковым исходным payload. Вы сможете показывать каждый язык по мере возврата результата, но вам придётся управлять 14 сетевыми запросами с дублирующимися данными, а при сбое одного из них логика повторов ляжет на вас.
Перевести все 14 в одном синхронном вызове — сетевых запросов меньше, но теперь придётся ждать самую медленную локаль, прежде чем вы сможете показать хотя бы одну.
В обоих случаях приложение занято, пока выполняется перевод. Если сервер перезапустится посреди процесса, все переводы в работе потеряются. Если одна локаль завершится ошибкой, обрабатывать частичный сбой придётся вам. И ни один из этих подходов не даёт пользователям понятного сигнала о том, что перевод уже идёт.
Асинхронный API убирает этот компромисс. Один запрос создаёт группу задач, где на каждую целевую локаль приходится отдельная задача. Каждая задача выполняется независимо через ваш движок локализации как надёжный фоновый Процесс, поэтому перезапуск сервера на вашей стороне ничего не ломает: работа не идёт внутри вашего процесса. Результаты доставляются по каждой локали сразу после завершения. Приложение остаётся отзывчивым. Сбои остаются изолированными. Платформа берёт на себя повторы и доставку.
Одна локаль и можно подождать секунду? Используйте sync.
Асинхронный API особенно хорошо раскрывается, когда у вас много локалей, длинный контент или UI, в котором важно показывать прогресс. Если вам нужна только одна пара локалей и вы можете подождать один сетевой запрос, синхронный endpoint Localize будет проще: один запрос, переведённые данные сразу в ответе, без необходимости поднимать webhook endpoint. Выбирайте async, когда задача слишком большая, слишком медленная или охватывает слишком много локалей, чтобы блокировать приложение.
Как это работает#
Всего три шага — и только первый происходит в цикле запрос/ответ вашего приложения. Остальные два платформа выполняет в своём собственном темпе.
Отправьте один запрос
Отправьте POST с контентом и целевыми локалями на /jobs/localization. API проверит payload, создаст группу задач с одной задачей на каждую локаль и вернёт 202 с идентификатором группы и краткой сводкой по задачам. После этого приложение может сразу продолжить работу — внутри этого вызова перевод не выполняется. Полный формат запроса и ответа см. в Create jobs.
Платформа обрабатывает каждую локаль независимо
Каждое задание проходит через движок локализации в рамках надёжного фонового рабочего процесса — с теми же настройками модели, глоссарием, тональностью бренда и правилами, что и синхронный API. При желании каждое задание можно провести через пайплайн с этапами пред-редактирования, ручной проверки, пост-редактирования, перефразирования и обратного перевода. Задание проходит путь от queued через processing до финального состояния: completed, completed_with_warnings или failed — и результат одной локали никогда не блокирует остальные.
Получайте результаты по мере готовности
Как только перевод для локали готов, платформа отправляет результат на ваш webhook URL. Если вам нужен живой прогресс в UI — например, счётчик «3 из 14 готово», который обновляется по мере завершения задач, — подключитесь к WebSocket группы. Если вам удобнее забирать данные самостоятельно, опрашивайте группу по интервалу.
Аутентификация
Каждый запрос — REST и WebSocket — проходит аутентификацию через ваш заголовок X-API-Key. Ключи привязаны к организации и дают доступ ко всем движкам внутри неё. Подробности см. в Authentication, а создать ключ можно в API Keys.
Модель группы задач#
Одна отправка создаёт одну группу, в которой есть одна задача на каждую целевую локаль. В этом и состоит вся модель — и именно она помогает ответить на самые сложные вопросы.
Скептически настроенный читатель уже мысленно задаёт их по списку: что будет, если одна локаль завершится ошибкой, и что происходит с приложением, пока все эти задачи выполняются? Модель группы отвечает сразу на оба вопроса.
- Сбои изолированы, потому что каждая локаль — это отдельная задача. Если немецкий перевод завершился успешно, а японский — с ошибкой, немецкий будет доставлен как обычно, а у задачи для японского будет свой собственный
errorMessage. Группа получит статусpartial, а всё, что успешно отработало, всё равно будет доставлено. Сбой в одной локали не может откатить другую, которая уже завершилась. Полная семантика статусов описана в Track a job group. - Задачи в работе переживают перезапуск, потому что выполняются не в вашем процессе. Каждая задача — это надёжный фоновый Процесс на платформе. Если ваш сервер перезагрузится, ничего из того, что уже выполняется, не потеряется: вы просто переподключитесь или продолжите опрос, а группа окажется ровно там, где вы её оставили.
- Группа — это модель прогресса, которую легко привязать к UI. Сохраните
groupIdиз202, а затем стройте индикатор прогресса на основе доставок через webhook или снимков WebSocket. «3 из 14 языков готово» — это просто счётчик по дочерним задачам группы.
У этой модели есть и своя честная цена: потребуется немного интеграции, которой не требует синхронный вызов. Чтобы получать результаты, вам нужно поднять HTTPS webhook endpoint или держать серверный WebSocket, а также обрабатывать каждую локаль по мере поступления, а не читать все переведённые данные сразу из одного ответа. Взамен платформа берёт на себя повторы, изоляцию сбоев и доставку, а приложение никогда не блокируется из-за перевода.
Именно на такой компромисс и рассчитан асинхронный API: один запрос, все локали, результаты по мере готовности. Следующие страницы раскрывают, как это работает на практике.
