작업 그룹 추적하기

그룹을 생성하고 groupId를 받았다면, 이제 여러 로캘이 병렬로 번역됩니다. 작업이 마무리될 때까지 반복해서 확인해야 할 질문은 하나입니다. 지금 이 제출 전체 상태가 어떤가요? 로캘별 상태가 아니라 집계된 전체 상태입니다. 몇 개가 완료됐는지, 몇 개가 경고와 함께 결과를 생성했는지, 몇 개가 실패했는지, 몇 개가 아직 실행 중인지 말이죠.

이 엔드포인트가 바로 그 답을 반환합니다. 한 번의 폴링으로 모든 로캘의 상태를 하나의 응답에서 확인할 수 있습니다. 비동기 로컬라이제이션이 처음이라면 Async Localization API 개요부터 시작하세요.

이 페이지에서

• 작업 그룹 가져오기
• 응답
• 그룹 상태
• 얼마나 자주 폴링할지
• 한 로캘이 실패했을 때

작업 그룹 가져오기#

작업 그룹과 그에 속한 모든 하위 작업의 상태를 조회합니다.

GET /jobs/localization/groups/:groupId

X-API-Key 헤더에 API 키를 넣어 인증하세요. 그룹을 생성할 때 사용한 것과 같은 키입니다. groupId에는 202 응답에서 받은 ljg_ 접두사 형태의 id를 사용합니다.

응답#

응답은 제출 전체의 스냅샷입니다. 그룹 자체의 status, 네 가지 개수 필드, 그리고 각 상태를 가진 하위 작업들이 함께 들어 있습니다. 폴링할 때마다 확인하게 되는 객체가 바로 이것입니다.

{
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "status": "processing",
  "sourceLocale": "en",
  "totalJobs": 3,
  "completedJobs": 1,
  "completedWithWarningsJobs": 0,
  "failedJobs": 0,
  "jobs": [
    { "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:04.000Z" },
    { "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "processing", "warnings": [], "completedAt": null },
    { "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "queued", "warnings": [], "completedAt": null }
  ],
  "createdAt": "2026-03-16T10:30:00.000Z"
}

종료된 작업을 나타내는 세 개의 개수 필드, 즉 completedJobs, completedWithWarningsJobs, failedJobs를 합치면 완료된 로캘 수가 됩니다. 나머지 totalJobs는 아직 queued 또는 processing 상태입니다. 위 스냅샷에서는 3개 중 1개가 완료됐고 2개는 아직 진행 중이므로, jobs 배열을 훑어보지 않아도 개수만 보면 작업이 아직 끝나지 않았다는 걸 알 수 있습니다. 이 합이 totalJobs에 도달하면 그룹은 종료 상태에 도달한 것입니다.

각 작업의 warnings 배열에는 치명적이지 않은 pipeline 단계 실패가 표시됩니다. 예를 들어 pre-edit나 back-translation 단계가 중간에 빠진 경우가 그렇습니다. 배열이 비어 있지 않다면 작업 결과는 생성됐지만, 하나 이상의 선택적 단계가 완료되지 않았다는 뜻입니다. 번역된 outputData 자체는 단일 작업에 있으니, 완료된 로캘의 콘텐츠를 확인할 준비가 됐다면 그쪽을 조회하세요.

그룹 상태#

그룹의 status는 하위 작업들의 상태를 하나의 값으로 집계한 결과입니다. 종료 상태에 도달할 때까지 폴링하면 됩니다.

completed, completed_with_warnings, partial를 구분하는 것이 이 엔드포인트의 핵심입니다. 즉, "모든 로캘이 배포 완료됨", "모든 로캘이 배포 완료됐지만 일부는 경고가 있음", "일부 로캘은 배포됐고 일부는 배포되지 않음"을 구분할 수 있게 해줍니다. 그렇지 않으면 각 작업을 읽어가며 직접 재구성해야 할 세 가지 결과죠. partial는 오류가 아닙니다. 그룹이 현재 상태를 있는 그대로 명확하게 알려주는 값이며, 덕분에 코드에서도 이 상태를 기준으로 분기할 수 있습니다.

얼마나 자주 폴링할지#

폴링은 그룹을 추적하는 가장 단순한 방법이고, 짧게 끝나는 배치 작업이라면 충분히 괜찮습니다. 다만 한계도 분명합니다. 변경 여부와 상관없이 매번 요청을 왕복해야 하고, 어떤 로캘이 완료됐는지도 완료되는 즉시가 아니라 다음 폴링 시점에야 알 수 있습니다.

각 결과를 준비되는 즉시 받고 싶다면 폴링 대신 알림을 받으세요. 플랫폼은 완료된 각 로캘을 끝나는 즉시 webhook URL로 전달하고, 그룹의 WebSocket connection은 변경이 있을 때마다 전체 상태 스냅샷을 푸시하므로 UI가 별도 요청 없이 업데이트됩니다. 웹훅 엔드포인트나 지속 연결을 유지하는 것이 작업 자체보다 부담이 클 때는 폴링을, UI 지연 시간이 중요할 때는 푸시 방식을 선택하세요.

한 로캘이 실패했을 때#

"한 번에 여러 로캘로 번역"이라는 설명을 들으면 가장 먼저 드는 질문이 있습니다. 한 로캘이 실패하면 나머지는 어떻게 될까요? 답은 응답에 그대로 담겨 있습니다.

각 로캘은 서로 독립적인 작업입니다. 독일어는 성공하고 일본어는 실패하더라도, 독일어 번역은 정상적으로 완료되어 전달됩니다. 실패한 로캘 때문에 롤백되지는 않습니다. 실패한 작업은 그룹 내에서 status: "failed"로 표시되고, failedJobs가 증가하며, 그룹 전체 상태는 partial로 집계됩니다:

{
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "status": "partial",
  "sourceLocale": "en",
  "totalJobs": 3,
  "completedJobs": 2,
  "completedWithWarningsJobs": 0,
  "failedJobs": 1,
  "jobs": [
    { "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:04.000Z" },
    { "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:05.000Z" },
    { "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "failed", "warnings": [], "completedAt": null }
  ],
  "createdAt": "2026-03-16T10:30:00.000Z"
}

로캘 두 개는 배포됐고 하나는 배포되지 않았다는 사실을, 개수만 봐도 바로 알 수 있습니다. 다시 시도하려면 실패한 로캘만 포함해 새로운 idempotency key로 새 요청을 제출하세요. 실패한 로캘의 전체 오류 설명인 errorMessage는 단일 작업에 있습니다. 그룹은 개수와 최종 판정만 제공합니다.

다음 단계#