API ручной проверки

Находите целевые версии документов, ожидающие проверки, одобряйте переводы и отправляйте правки с правами проверяющего.

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

Для запросов к проверкам нужен доступ к организации и разрешение проверять переводы движка. Отправлять решения можно только от имени человека: для аутентификации используйте токен доступа сеанса проверяющего или личный ключ API. Сервисный ключ организации не позволяет отправлять решения ручной проверки.

Найти проверки #

http
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50

Ответ имеет вид { "data": [...], "meta": { "nextCursor": "..." } }. Используйте курсоры для перехода между страницами, пока nextCursor не примет значение null.

Поле запросаЗначения и значение по умолчанию
statusesopen, completed, timedOut, cancelled. По умолчанию — open. Чтобы указать несколько значений, повторите параметр.
orderoldest (по умолчанию) или newest.
limit1–100. По умолчанию — 50.
cursorНепрозрачный курсор с предыдущей страницы. Не меняйте фильтры и порядок сортировки.

Для запроса проверок со статусами принятых решений нужно разрешение на управление проверками организации. Каждая сводка содержит documentId, locale, jobId, engineId, engineName, documentKey, sourceLocale, provider, vendorStartedAt, status, readyAt, expiresAt, closedAt, totalUnits и pendingUnits.

Получить одну проверку #

http
GET /v2/localization/documents/:documentId/targets/:locale/review

Ответ содержит тот же контекст целевой версии и движка, а также units, сведения о передаче проверки и зарегистрированном внешнем заказе, если он есть. takeover имеет значение null, пока человек не возьмёт проверку на себя. externalOrder может отсутствовать или иметь значение null, если заказ не был зарегистрирован. Каждая единица содержит unitId, key, position, source, value, reference, quality, eligibility, result, decision, reviewerId и decidedAt.

Используйте sourceText, чтобы показать исходный текст, а valueText — как начальное значение для редактирования. После принятия решения показывайте settledText: это поле содержит принятую правку или другой окончательный результат, а valueText хранит перевод до проверки. Пока результат недоступен, settledText равно valueText.

quality — результат контроля качества для единицы: { "findings": [...] }, как описано в справочнике по пайплайну, или null, если единица не проходила контроль качества. eligibility имеет значение required, qualityPassed, localeNotCovered или reused. Решение человека нужно только для обязательных единиц, по которым оно ещё не принято. Остальные единицы служат контекстом. Окончательное значение result, отличное от null, может означать, что истёк срок ожидания или применён резервный вариант. Проверьте decision, чтобы узнать, одобрил ли человек единицу или внёс в неё правки.

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

Одобрить или изменить #

Одобрите все оставшиеся обязательные единицы без изменений:

http
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-all

У этого запроса нет тела. Чтобы явно указать решения, отправьте POST-запрос на /decisions с непустым массивом и уникальными ИД единиц:

json
{
  "decisions": [
    { "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
    { "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
  ]
}

Используйте ИД из полученной проверки. Чтобы изменить структурированное значение, возьмите за основу его valueText и отправьте изменённый текст как Edited.value. Например, Hello {name}<C1>world</C1><C2/> может стать Bonjour {name}<C1>tout le monde</C1><C2/>. Сохраняйте токены плейсхолдеров, их количество и вложенность разметки. Плейсхолдеры на одном уровне вложенности можно перемещать. Символы разделителей, которые входят в сам структурированный текст, экранируются с помощью сущностей. API разбирает этот текст и преобразует его обратно в структурированные сегменты. Вы также можете отправить массив структурированных сегментов напрямую. При редактировании ICU в обычных строках сохраняйте локализованные варианты и числовые значения перевода.

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

LocalizationReviewInvalid (422) указывает на некорректные данные, в том числе изменённые плейсхолдеры. LocalizationReviewClosed (409) означает, что проверка или единица больше не принимает это решение. Повторный запрос после завершения работы над целевой версией может вернуть 409, даже если первая отправка прошла успешно. Если ответ потерян, получите проверку и сравните сохранённые решения и ИД проверяющих, прежде чем решать, что делать дальше.

Внешняя проверка и её передача #

Проверьте GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status, чтобы узнать текущее состояние у внешнего поставщика: unstarted, inProgress, completed или unknown.

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

Дождаться итогового файла #

Крайний срок проверки — expiresAt, рассчитанный на основе readyAt. Опрос и повторные запросы его не продлевают. По истечении срока у единиц без решения сохраняются предыдущие переводы с предупреждениями. Принятые решения остаются в силе.

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