Задания на перевод
Создавайте и запускайте задания для перевода одного или нескольких документов на один или несколько языков.
В каждом задании документы переводятся с помощью одного движка локализации. У каждого документа есть постоянный ключ и отдельный целевой перевод для каждого запрошенного языка. Для содержимого в памяти используйте встроенный JSON, а для файлов — адреса артефактов.
Все маршруты ниже используют https://api.lingo.dev и аутентификацию API.
Создание задания #
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr{
"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 с аутентификацией и исходными байтами. Затем вызовите:
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEYУ запроса на запуск нет тела. В ответе HTTP 200 возвращается текущая запись задания. Повторный запрос на запуск того же задания безопасен и позволяет повторить отправку на выполнение, если её результат неясен. Он не создаёт новое задание и не запускает заново уже завершённое.
При запуске проверяются загруженные артефакты, конфигурация движка и лимиты учётной записи. Ошибка ArtifactsNotUploaded (409) содержит список недостающих входных данных. Если достигнут суточный лимит токенов (429) или не хватает кредитов, задание остаётся в ожидании. Устраните причину, прежде чем запускать его снова. См. ошибки.
Настройка этапов пайплайна #
Настройте пайплайн движка перед запуском. Его конфигурация фиксируется в момент запуска. Итоговый набор этапов для каждого целевого перевода показывает, какая работа выбрана с учётом доступности этапов в плане.
Получение результатов и восстановление после сбоев #
Получите данные задания, чтобы проверить каждый целевой перевод и скачать готовые файлы. По ходу выполнения этапов вы можете определить, где работает модель, где ожидается проверка, какая работа пропущена и где произошёл сбой.
Даже если задание завершилось с ошибкой, часть целевых переводов может быть готова. Сохраните эти результаты, устраните причину сбоя и отправьте с новым ключом идемпотентности только ту работу, которую нужно выполнить повторно. Храните версии исходных документов вместе с ИД заданий, чтобы результаты, поступившие позже, не перезаписали более новые переводы.
Получите список заданий, чтобы найти отправленные задания по движку, состоянию, триггеру или сервисному ключу.