Как получить данные задания на перевод
Проверяйте целевые переводы документов, дожидайтесь завершения и скачивайте доступные результаты.
Получите данные задания с помощью id, полученного при создании:
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. |
status | Pending, Completed или Failed в поле _tag. |
stages | Ход выполнения этапов, включая статус и количество единиц. |
Статус готового целевого перевода содержит artifact и downloadUrl, а статус перевода, завершившегося с ошибкой, — message. В этом фрагменте ответа показан статус готового целевого перевода:
{
"_tag": "Completed",
"artifact": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"downloadUrl": "/v2/localization/jobs/lfr_example/artifacts/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}Используйте именно те адрес и URL, которые вернулись в ответе. URL задан относительно https://api.lingo.dev, а для доступа по нему нужна аутентификация. Это не общедоступная подписанная ссылка для скачивания. При скачивании возвращаются байты файла в формате документа.
Несколько целевых переводов могут использовать один артефакт. Каталог строк Apple объединяет запрошенные языки в одном файле .xcstrings. Сохраните этот общий результат один раз и проверьте в нём записи локалей. Не считайте каждый скачанный файл отдельным одноязычным каталогом.
Как опрашивать задание и собирать результаты #
Опрашивайте задание через заданные интервалы, например раз в две секунды, и ограничьте время ожидания в приложении. Если временно не удаётся получить данные, сохраните ИД и повторяйте попытки с увеличением задержки. Если прекратить ожидание, обработка на сервере продолжится. Ручная проверка может занять значительно больше времени, чем короткий тайм-аут запроса приложения.
Скачайте целевой перевод, как только его статус станет Completed. Если приложению нужно опубликовать все языки одновременно, дождитесь всех необходимых целевых переводов и обеспечьте соблюдение этого правила публикации в своём хранилище. Один готовый файл не означает, что перевод для каждой локали завершился успешно.
Полный пример программы для опроса и скачивания результатов вы найдёте в кратком руководстве. О том, как работать с версиями исходных данных и решать, когда повторять попытки, читайте в руководстве «Как создать рабочий процесс перевода».