Как настроить рабочий процесс перевода через API
Переводите записи приложения на сервере и сохраняйте связь принятых языковых версий с соответствующей редакцией исходного текста.
Когда редактор обновляет описание товара, каждый перевод должен отражать это изменение. Ответ API содержит новый текст, а ваше приложение решает, к какой записи он относится, актуален ли ещё исходный текст и когда перевод станет доступен читателям.
Это руководство поможет превратить первый запрос на перевод в повторяемый рабочий процесс на сервере. Он подходит для записей, которыми управляет ваше приложение, например описаний товаров и справочных статей. Для статических ресурсов приложения часто лучше подходит рабочий процесс с файлами в CI: их уже можно проверить при компиляции ресурсов и проверке изменений в репозитории.
Отправляйте логически связанный контент #
Создайте задание на локализацию с одним встроенным JSON-документом для записи о товаре. Сгруппируйте связанные поля, чтобы описать их назначение в контексте. Сохраняйте ключи неизменными, чтобы сопоставить скачанный объект с этими полями.
Отправьте это тело запроса в POST /v2/organizations/:orgId/localization/jobs, указав ключ API и стабильный Idempotency-Key для этой редакции:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "products/bottle.json",
"format": {
"type": "json",
"options": {
"context": "Product listing for a reusable drinks bottle",
"hints": {
"$.title": ["Catalog card title"],
"$.description": ["Short product description; do not add specifications"]
}
}
},
"source": {
"content": {
"title": "Insulated bottle",
"description": "Keeps drinks cold during your commute."
}
}
}
]
}Храните учётные данные на сервере и явно указывайте движок. Задавайте терминологию продукта в общем глоссарии, а сведения о конкретном сценарии — в контексте документа. Подробнее о подсказках и защищённых путях — в справочнике по JSON.
Выполняйте перевод в фоновом режиме #
Перед запуском задания сохраните полученный ИД. Загрузите всё, что перечислено в uploads, затем вызовите POST /v2/localization/jobs/:id/start. Даже для встроенного JSON задание нужно запустить явно.
Опрашивайте задание из фонового обработчика на сервере и скачивайте готовые переводы по URL из ответа. Запрос редактора на сохранение может завершиться, как только приложение надёжно поставит эту работу в очередь. Держать запрос открытым, пока идёт перевод или ручная проверка, не нужно.
Для инкрементальных обновлений сохраняйте предыдущий исходный документ и принятые переводы. Передавайте их в следующем запросе на обработку документа. В каких пределах их можно использовать повторно, описано в разделе Обновление документов.
Создавайте запись о работе после сохранения исходного текста #
После фиксации транзакции с исходным текстом создайте в своём хранилище запись о работе. Укажите в ней ИД контента, редакцию исходного текста, целевую локаль, запись о движке локализации и его конфигурации, а также состояние обработки. Ставьте перевод в очередь на основе этой записи. Так обработчик не начнёт переводить изменение, которое позже будет отменено при откате транзакции.
Храните отдельный результат для каждого целевого языка. Немецкий перевод может быть готов, а французский — требовать повторной попытки или проверки. Один общий флажок «переведено» скроет эту разницу от приложения, которое решает, что показывать. Все названия состояний, которые вы добавляете, — часть логики вашего приложения, а не набор значений из ответов API.
Принимайте результат только для нужной редакции #
Изменения исходного текста и готовые переводы могут поступать в разном порядке. Например:
| Событие | Действие приложения |
|---|---|
| Сохранена редакция 12 | Поставить редакцию 12 в очередь на перевод на немецкий. |
| Редакция 13 сохранена до завершения этой работы | Поставить редакцию 13 в очередь и отметить её как текущую редакцию исходного текста. |
| Перевод редакции 13 завершён | Проверить и принять его для редакции 13. |
| Перевод редакции 12 завершён позже | Сохранить результат, не заменяя принятый текст редакции 13. |
В момент активации сравните редакцию исходного текста в записи о работе с текущей. В хранилище выполняйте запись при условии, что редакция по-прежнему совпадает с проверенной. Так новое изменение исходного текста между сравнением и записью не останется незамеченным. Если работа для текущей редакции не была поставлена в очередь или завершилась с ошибкой, запланируйте её обработку, а не привязывайте старый результат к новой редакции.
При чтении запрашивайте принятый перевод для нужного языка и редакции. Решите, что приложение будет делать, если перевода нет: показывать исходный текст, использовать заданный резервный язык, выдавать старый перевод с явным учётом его редакции или откладывать публикацию. Выбор зависит от того, какие последствия устаревший или непереведённый текст может иметь для читателя. Изменённые условия checkout могут требовать более строгой политики, чем обычное описание товара.
Восстанавливайте работу по удалённому идентификатору и локальной записи #
Сохраните ключ идемпотентности до отправки запроса, а ИД задания — сразу после получения ответа о его создании. Если время ожидания ответа по сети истекло, повторите тот же запрос на создание с тем же ключом или получите задание по сохранённому ИД. Повторный вызов запуска работает с тем же заданием.
После временных ошибок чтения продолжайте опрос, увеличивая интервалы между попытками. Когда время ожидания на клиенте истекает, сервер продолжает работу. Храните готовые переводы отдельно от сведений об ошибках для целевых языков: даже задание, завершившееся с ошибкой, может содержать готовые файлы, пригодные для использования.
Ошибки аутентификации, отключённые движки, некорректные входные данные и ограничения учётной записи требуют исправления. Ожидающее задание можно запустить повторно, когда ограничение на допуск к выполнению больше не мешает запуску. Если задание завершилось с ошибкой во время выполнения, устраните причину и отправьте затронутые документы и локали с новым ключом идемпотентности.
При принятии каждого результата выполняйте ту же проверку редакции, в том числе для результатов, полученных после восстановления. Завершённое скачивание означает лишь, что текст доступен. Можно ли его публиковать, определяют ваши правила валидации и проверки.
Протестируйте жизненный цикл записи #
Возьмите короткую запись с переменной и протестируйте обновление исходного текста, ошибку для одной из локалей и завершение переводов не по порядку. Проверьте не только текст, но и сохранённые ключи полей и идентификаторы языков. Приложение должно выдавать только версию, которую допускает ваша политика, а при проверке должна быть возможность проследить её связь с исходным текстом.
Для измерения качества сохраняйте исходный текст и перевод в паре вместе с критерием, по которому их оценивали. Проектирование измерений не зависит от рабочего процесса генерации. Так в записи можно отдельно учитывать полученный текст, ответ по результатам измерения, принятие человеком и публикацию, а не считать их одним событием.