휴먼 리뷰 API
검토 권한이 있는 검토자로서 대기 중인 문서 대상을 찾고, 번역을 승인하고, 수정 사항을 제출하세요.
검토 한 건은 문서 하나의 대상 언어 하나를 다룹니다. 설정된 휴먼 리뷰 단계에서 결정 요건을 충족하는 단위가 준비되면 검토할 수 있습니다. 작업을 시작하기 전에 결정 풀 라우팅을 설정하세요.
검토를 요청하려면 조직 접근 권한과 엔진의 번역을 검토할 권한이 필요합니다. 결정을 요청할 때는 개인 인증도 필요합니다. 검토자의 세션 액세스 토큰이나 개인 API 키로 인증하세요. 조직 서비스 키로는 사람이 내린 결정을 제출할 수 없습니다.
검토 찾기 #
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50응답은 { "data": [...], "meta": { "nextCursor": "..." } }입니다. nextCursor 값이 null 값이 될 때까지 커서를 따라 다음 페이지를 조회하세요.
| 쿼리 필드 | 값 및 기본값 |
|---|---|
statuses | open, completed, timedOut, cancelled. 기본값은 open입니다. 여러 값을 지정하려면 같은 매개변수를 반복해서 사용하세요. |
order | oldest(기본값) 또는 newest. |
limit | 1~100. 기본값은 50입니다. |
cursor | 이전 페이지에서 받은 불투명 커서입니다. 필터와 정렬 순서는 그대로 유지하세요. |
결정이 완료된 상태를 조회하려면 조직의 검토를 관리할 권한이 필요합니다. 각 요약에는 documentId, locale, jobId, engineId, engineName, documentKey, sourceLocale, provider, vendorStartedAt, status, readyAt, expiresAt, closedAt, totalUnits, pendingUnits 항목이 명시됩니다.
검토 한 건 조회 #
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 값이 널이 아니더라도 시간 초과나 대체 처리의 결과일 수 있습니다. 사람이 해당 단위를 승인하거나 수정했는지 확인하려면 decision을 살펴보세요.
value은 검토 단계에 진입한 시점의 번역입니다. 문자열이거나 텍스트, 변수, 마크업으로 구성된 구조화된 세그먼트 배열일 수 있습니다. 수정할 때는 플레이스홀더의 식별 정보와 중첩 구조를 유지하세요.
승인 또는 수정 #
남은 필수 단위를 모두 변경 없이 승인하려면 다음과 같이 요청하세요.
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-all이 요청에는 본문이 없습니다. 개별 결정을 명시하려면 비어 있지 않은 배열과 중복되지 않는 단위 식별자를 담아 /decisions에 전송하세요.
{
"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 중 하나입니다.
외부 검토를 인계받으려면 남은 필수 단위 모두에 대한 결정을 한 번에 제출해야 합니다. 그러면 외부 검토가 종료되고 제공업체의 주문 취소가 시도됩니다. 이미 시작된 작업에는 요금이 부과될 수 있습니다. 조회 시점과 제출 시점 사이에 제공업체의 상태가 바뀔 수 있으므로, 조회한 상태가 무료 취소를 보장하지는 않습니다.
최종 파일 기다리기 #
검토 기한은 readyAt를 기준으로 계산한 expiresAt입니다. 폴링하거나 재시도해도 기한은 연장되지 않습니다. 시간이 초과되면 결정이 내려지지 않은 단위는 경고와 함께 이전 번역을 유지하며, 승인된 결정은 그대로 유지됩니다.
검토가 끝난 뒤에도 후속 파이프라인 단계에서 텍스트가 변경될 수 있습니다. 최종 파일을 받으려면 작업을 조회하고 완료된 대상을 다운로드하세요. 완료된 검토 자체가 다운로드할 최종 결과물은 아닙니다.