API 작업에 휴먼 리뷰 통합하기

번역을 검토자에게 전달하고, 검토자의 결정을 추적하고, 최종 문서 결과물을 수집하세요.

번역을 전달하기 전에 사람의 판단이 필요하다면 휴먼 리뷰를 추가하세요. 엔진은 각 문서와 대상 언어를 결정 풀로 전달합니다. 검토자가 검토 대상 단위를 승인하거나 수정하면 파이프라인이 다운로드 가능한 파일을 생성하는 단계로 계속 진행됩니다.

먼저 정상적으로 작동하는 API 번역을 준비하세요. 휴먼 리뷰를 지원하는 요금제 기능, 결정 풀, 엔진의 번역에 접근할 수 있는 검토자도 필요합니다.

시작 전에 검토 설정하기 #

엔진의 파이프라인 탭을 열고 휴먼 리뷰를 활성화하세요. 결정 풀과 언어를 선택하고, 필요하면 디렉터리 범위도 지정하세요. 디렉터리 라우팅은 각 문서와 함께 전송하는 key 값을 기준으로 하므로 emails/order-confirmation.json처럼 일관된 경로를 사용하세요.

지정한 경로에서 새로 번역된 콘텐츠를 모두 검토하려면 전체를 선택하세요. 이 옵션에서는 품질 게이트가 꺼진 상태로 유지됩니다. 선택적으로 검토하려면 엄격, 보통, 느슨함 중 하나를 선택하세요. 품질 게이트는 오류를 심각도 및 범주와 함께 표시하며, 선택한 수준에 따라 검토가 필요한 심각도가 정해집니다. 품질 게이트가 확인하지 못한 번역도 검토 대상으로 전달됩니다. 각 수준에 대한 설명은 품질 게이트 수준을 참고하세요. 재사용된 번역은 읽기 전용 참고 정보로 제공되며, 자동으로 새 검토 작업이 되지는 않습니다.

검토 팀에 적합한 제한 시간을 선택하세요. 대상이 준비되는 시점부터 제한 시간이 시작됩니다. 시간이 만료되면 응답이 없는 단위는 검토 직전의 번역으로 다음 단계를 진행할 수 있습니다. 게시되는 모든 번역에 사람의 결정이 필요하다면 애플리케이션의 게시 전 확인 절차에서 이 요건을 반드시 충족하도록 해야 합니다.

애플리케이션에서 엔진 설정을 관리한다면 API를 통해 파이프라인을 구성하세요.

콘텐츠 제출하기 #

작업을 생성하고 누락된 아티팩트를 업로드한 다음 /start 호출을 실행하세요. 작업 식별자를 원본 리비전 및 적용할 검토 정책과 함께 저장하세요. 엔진의 파이프라인 구성은 작업 시작 시점에 저장됩니다. 이후 구성을 변경해도 실행 중인 작업의 검토 정책은 바뀌지 않습니다.

작업의 문서 식별자와 대상 로캘을 확인하세요. 대상의 단계별 진행 상황에 표시되는 humanEdit 값은 검토 작업을 나타내며, 검토 API에서 실제 검토 단위와 결정을 확인할 수 있습니다. 검토자가 작업하는 동안 작업 상태는 Running 상태로 유지될 수 있습니다.

검토자에게 필요한 맥락 제공하기 #

검토자는 대시보드의 큐 → 유형 → 휴먼 리뷰에서 검토할 수 있습니다. 이 화면에는 품질 게이트의 검사 결과가 번역 옆에 표시됩니다. 검토자는 변경 없이 승인하거나 번역을 수정한 뒤 제출할 수 있습니다. 검토자가 원문, 대상 언어, 자리표시자, 사용해야 할 용어를 볼 수 있도록 하세요.

애플리케이션에서 자체 검토 인터페이스를 제공한다면 GET /v2/organizations/:orgId/localization/reviews 호출로 미완료 검토 목록을 조회한 다음, 선택한 문서와 로캘의 검토를 가져오세요. 결정을 제출할 때는 백그라운드 서비스의 조직 키가 아니라 개인 키나 사용자 세션을 사용해 검토자로 인증하세요.

필수 단위에 대해 Approved 또는 Edited 결정을 제출하세요. 내부 검토에서는 일부 단위만 제출할 수 있습니다. 외부 검토를 인계받으려면 남은 모든 필수 단위에 대한 결정을 한 번에 제출해야 하며, 이 경우에도 제공업체의 요금이 부과될 수 있습니다. 정확한 요청 데이터와 오류는 검토 레퍼런스에서 확인하세요.

최종 결과 수집 및 검증하기 #

검토자가 제출한 뒤에도 현지화 작업을 계속 조회하세요. 대상이 Completed 상태가 된 후에만 다운로드하세요. 후편집, 길이 처리, 역번역이 계속 실행될 수 있으므로 검토 완료와 파일 생성 완료는 별개입니다.

사람이 승인한 문구를 그대로 사용해야 한다면 이후의 재작성 단계를 비활성화하고 최종 결과물을 확인하세요. 승인 증빙이 필요하다면 검토 결정과 제한 시간이 초과된 단위를 확인하세요. 단계가 완료되었다는 사실만으로 사람이 모든 단위를 승인했다고 간주해서는 안 됩니다.

원본 리비전이 여전히 일치하고 필수 검토 정책이 충족된 경우에만 게시하세요. 늦게 도착한 번역이 더 최신 원본 리비전의 결과물을 덮어쓰지 않도록 하세요.

중단 상황에서 복구하기 #

클라이언트에서 시간 초과가 발생해도 기존 작업과 검토의 식별자를 유지하세요. 새 작업을 만들면 별도의 번역 및 검토 절차가 시작됩니다. 결정 제출에 대한 응답이 유실되었다면 검토를 조회해 저장된 결정과 검토자 식별자를 확인하세요. 대상이 아직 제출을 허용하는 동안에는 같은 검토자가 동일한 결정을 다시 제출할 수 있습니다. 다만 이미 완료된 대상은 첫 제출이 성공했더라도 409를 반환할 수 있습니다. 성공적으로 제출된 결정은 최종 확정됩니다.

검토 기한이 되면 수락된 결정, 응답이 없는 단위, 생성된 파일을 확인하세요. 완료된 작업을 보존하고 다음 조치를 신중하게 선택하세요. 게시를 보류하거나, 추가 검토를 받거나, 명시적으로 정의된 대체 방안을 수용할 수 있습니다.