Задания на перевод

Создавайте и запускайте задания для перевода одного или нескольких документов на один или несколько языков.

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

Все маршруты ниже используют https://api.lingo.dev и аутентификацию API.

Создание задания #

http
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr
json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "order-confirmation.json",
      "format": { "type": "json" },
      "source": { "content": { "subject": "Your order is confirmed" } }
    }
  ]
}

Поля запроса #

ПолеОбязательноОписание
engineIdДаДвижок организации, который вызывающая сторона может использовать для перевода.
sourceLocaleДаИсходный язык.
targetLocalesДаНепустой массив уникальных целевых локалей. Целевая локаль документа не может совпадать с исходной.
documentsДаНепустой массив документов с уникальными значениями key.
originIdНетНепустой идентификатор места хранения документов длиной до 512 символов, например github:acme/web. Он связывает последующие правки из этого источника с измерением качества перевода.

Поля каждого документа:

ПолеОбязательноОписание
keyДаНепустой логический путь к файлу или имя, уникальные в рамках задания. Не меняйте это значение при переходе от одной версии к другой.
formatДаОбъект формата с type и параметрами options, которые зависят от формата.
sourceДаАдрес артефакта SHA-256 или { "content": { ... } } для встроенного JSON.
previousSourceНетАдрес артефакта предыдущей версии исходного документа. Для первого перевода не передавайте поле или укажите null.
previousTranslationsНетМассив { "locale": "de", "artifact": "SHA256" }. По умолчанию — []. Каждая локаль должна быть уникальной и входить в число целевых локалей этого документа.
targetLocalesНетНепустой набор уникальных локалей, заданный отдельно для этого документа. Если поле не передано или указано null, используются целевые локали задания.

При использовании keyScope или termScope передайте предыдущий перевод для каждого целевого языка. См. форматы документов и обновления.

Идемпотентность #

Передайте непустое значение Idempotency-Key длиной не более 255 символов. Ключи действуют в пределах движка. Префикс content-sync: зарезервирован. Сохраните ключ вместе с исходным запросом. Если результат запроса на создание неясен, повторите запрос без изменений.

При повторном использовании ключа возвращается задание, изначально созданное с этим ключом. Документы и локали задания не обновляются. Если нужно изменить состав работы, используйте новый ключ. Конфликтующий параметр запуска может привести к ошибке LocalizationJobIdempotencyKeyReused (422).

Ответ на запрос создания #

При успешном создании возвращаются HTTP 200 и ответ с данными задания, обычно с status: { "_tag": "Pending" }. Прежде чем продолжить, сохраните id. В массиве uploads перечислены недостающие входные артефакты в виде { "address": "...", "uploadUrl": "..." }.

При создании задания сохраняются встроенные исходные данные. Перевод не запускается, даже если uploads пуст.

Загрузка и запуск #

Загрузите каждый недостающий артефакт по адресу uploadUrl, отправив запрос PUT с аутентификацией и исходными байтами. Затем вызовите:

http
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEY

У запроса на запуск нет тела. В ответе HTTP 200 возвращается текущая запись задания. Повторный запрос на запуск того же задания безопасен и позволяет повторить отправку на выполнение, если её результат неясен. Он не создаёт новое задание и не запускает заново уже завершённое.

При запуске проверяются загруженные артефакты, конфигурация движка и лимиты учётной записи. Ошибка ArtifactsNotUploaded (409) содержит список недостающих входных данных. Если достигнут суточный лимит токенов (429) или не хватает кредитов, задание остаётся в ожидании. Устраните причину, прежде чем запускать его снова. См. ошибки.

Настройка этапов пайплайна #

Настройте пайплайн движка перед запуском. Его конфигурация фиксируется в момент запуска. Итоговый набор этапов для каждого целевого перевода показывает, какая работа выбрана с учётом доступности этапов в плане.

Получение результатов и восстановление после сбоев #

Получите данные задания, чтобы проверить каждый целевой перевод и скачать готовые файлы. По ходу выполнения этапов вы можете определить, где работает модель, где ожидается проверка, какая работа пропущена и где произошёл сбой.

Даже если задание завершилось с ошибкой, часть целевых переводов может быть готова. Сохраните эти результаты, устраните причину сбоя и отправьте с новым ключом идемпотентности только ту работу, которую нужно выполнить повторно. Храните версии исходных документов вместе с ИД заданий, чтобы результаты, поступившие позже, не перезаписали более новые переводы.

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