Как получить данные задания на перевод

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

Получите данные задания с помощью id, полученного при создании:

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

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

Поля задания #

ПолеЗначение
id, organizationId, engineIdИдентификатор задания, организация-владелец и движок.
sourceLocaleИсходный язык.
triggerИсточник, например api, cli, ci или интеграция.
statusСостояние задания с меткой типа. Описание состояний — ниже.
createdAt, updatedAtСтроки с отметками времени в формате ISO.
createdByСведения о создателе или null, если они недоступны. Если использован личный ключ, создателем считается пользователь, которому он принадлежит.
documentsДокументы, их форматы, адреса исходных файлов и ход выполнения целевых переводов.
uploadsАдреса недостающих артефактов и URL для загрузки, пока задание ожидает запуска. После запуска поле пустое.

Состояния задания #

status._tagЧто делать
PendingЗагрузите недостающие артефакты и вызовите /start.
RunningПовторите опрос позже. Проверьте этапы целевых переводов, чтобы узнать, идёт ли работа или ожидается проверка.
CompletedСкачайте и проверьте результаты. При приёмке также проверьте предупреждения на этапах.
FailedИзучите status.message и ошибки целевых переводов. Готовые целевые переводы остаются доступны.
CancelledРабота остановлена. Проверьте, есть ли уже готовые результаты целевых переводов.

Completed, Failed и Cancelled — конечные состояния задания. При частичном сбое задание считается завершившимся с ошибкой: часть целевых переводов готова, а часть завершилась с ошибкой.

Поля документа и целевого перевода #

Каждый документ содержит id, key, format, source, previousSource и targets. source — адрес артефакта, даже если JSON передан прямо в запросе. Если previousSource отсутствует, его значение — null.

Каждый целевой перевод содержит:

ПолеЗначение
localeЦелевой язык.
previousTranslationАдрес предыдущего артефакта целевого перевода или null.
statusPending, Completed или Failed в поле _tag.
stagesХод выполнения этапов, включая статус и количество единиц.

Статус готового целевого перевода содержит artifact и downloadUrl, а статус перевода, завершившегося с ошибкой, — message. В этом фрагменте ответа показан статус готового целевого перевода:

json
{
  "_tag": "Completed",
  "artifact": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "downloadUrl": "/v2/localization/jobs/lfr_example/artifacts/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Используйте именно те адрес и URL, которые вернулись в ответе. URL задан относительно https://api.lingo.dev, а для доступа по нему нужна аутентификация. Это не общедоступная подписанная ссылка для скачивания. При скачивании возвращаются байты файла в формате документа.

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

Как опрашивать задание и собирать результаты #

Опрашивайте задание через заданные интервалы, например раз в две секунды, и ограничьте время ожидания в приложении. Если временно не удаётся получить данные, сохраните ИД и повторяйте попытки с увеличением задержки. Если прекратить ожидание, обработка на сервере продолжится. Ручная проверка может занять значительно больше времени, чем короткий тайм-аут запроса приложения.

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

Полный пример программы для опроса и скачивания результатов вы найдёте в кратком руководстве. О том, как работать с версиями исходных данных и решать, когда повторять попытки, читайте в руководстве «Как создать рабочий процесс перевода».