단일 작업 조회

한 로캘의 번역 결과와 생성 과정의 단계별 기록을 확인합니다.

이 엔드포인트는 이미 jobId를 갖고 있을 때 사용합니다. 이 값은 create의 202 응답으로 반환되거나, webhook에 실려 오거나, job group 아래에 나열됩니다. 그룹 엔드포인트가 완료된 로캘이 몇 개 인지 알려준다면, 이 엔드포인트는 단일 로캘이 무엇을 생성했는지와 그 과정에서 어떤 일이 있었는지를 보여줍니다.

text

GET /jobs/localization/:jobId

비동기 로컬라이제이션이 처음이신가요? 개요부터 시작하세요.

바로 이 차이가 이 페이지의 핵심입니다. 그룹 응답은 스코어보드처럼 개수와 작업별 상태를 보여주며, job-group 페이지에서 다룹니다. 반면 단일 작업은 한 로캘의 전체 기록입니다. 번역된 outputData, 최종 status, 모든 warnings, 그리고 pipeline이 거친 모든 단계의 steps[] 추적 기록이 담겨 있습니다. 데이터베이스에 독일어 카피를 기록할 준비가 됐다면, 이 호출이 바로 그 독일어 카피를 건네줍니다.

인증#

API 키를 X-API-Key 헤더에 전달하세요. 키는 조직 범위로 적용되며 해당 조직의 모든 엔진에 접근할 수 있습니다. 자세한 내용은 Authentication을 참고하세요.

응답#

outputData 필드는 입력 data의 구조를 그대로 반영합니다. 모든 문자열 값은 번역되고, 문자열이 아닌 값(숫자, 불리언, null)은 원래 위치에 그대로 유지됩니다. 키도 같고, 중첩 구조도 같고, 배열 순서도 같습니다. 바뀌는 것은 문자열뿐입니다.

json

{
  "id": "ljb_A1b2C3d4E5f6G7h8",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "targetLocale": "de",
  "status": "completed",
  "outputData": {
    "id": "course_101",
    "title": "Einführung in maschinelles Lernen",
    "steps": [
      { "heading": "Was ist ML?", "body": "Maschinelles Lernen ist ein Teilbereich der künstlichen Intelligenz." },
      { "heading": "Überwachtes Lernen", "body": "Trainieren eines Modells mit gelabelten Daten." }
    ],
    "metadata": { "author": "Dr. Smith", "difficulty": "beginner" }
  },
  "errorMessage": null,
  "warnings": [],
  "callbackStatus": "delivered",
  "createdAt": "2026-03-16T10:30:00.000Z",
  "startedAt": "2026-03-16T10:30:01.000Z",
  "completedAt": "2026-03-16T10:30:04.000Z",
  "steps": [
    {
      "stepId": "localize",
      "type": "action",
      "status": "completed",
      "errorMessage": null,
      "externalRefType": null,
      "externalRefId": null,
      "externalRefUrl": null,
      "createdAt": "2026-03-16T10:30:01.000Z",
      "startedAt": "2026-03-16T10:30:01.000Z",
      "completedAt": "2026-03-16T10:30:04.000Z"
    }
  ]
}

위의 metadata 블록은 그대로 보존되었습니다. Dr. Smith와 beginner는 엔진이 손대지 않은 비문자열 리프 값입니다. 다시 받아보는 outputData는 보낸 형태와 같은 구조를 유지하므로, 페이로드를 만들던 같은 코드로 번역 결과도 그대로 처리할 수 있습니다.

필드	설명
`id`	이 작업 자체의 ID(`ljb_…`)입니다. 경로에 전달한 바로 그 값입니다.
`groupId`	이 작업이 속한 상위 job group(`ljg_…`)입니다. 모든 형제 로캘을 한 번에 보려면 job-group 엔드포인트에 전달하세요.
`targetLocale`	이 작업이 번역한 대상 BCP-47 로캘입니다. 대상 로캘마다 작업이 하나씩 존재합니다. `outputData`를 올바른 열이나 파일로 라우팅할 때 기준이 되는 필드입니다.
`status`	`queued`, `processing`, `completed`, `completed_with_warnings` 또는 `failed`입니다.
`outputData`	입력 구조와 일치하는 번역된 콘텐츠입니다. `status`가 `completed` 또는 `completed_with_warnings`일 때 제공됩니다.
`errorMessage`	오류 설명입니다. `status`가 `failed`일 때 제공되며, 그 외에는 `null`입니다.
`warnings`	치명적이지 않은 pipeline 단계 실패입니다. 각 항목은 `{ step, message }`입니다. `status`가 `completed_with_warnings`인 경우가 아니면 비어 있습니다.
`callbackStatus`	Webhook 전송 상태입니다: `pending`, `delivered` 또는 `failed`. 콜백 URL이 설정되어 있지 않으면 `null`입니다.
`createdAt`	작업이 수락된 시점입니다(작업을 생성한 `202`의 타임스탬프).
`startedAt`	엔진이 이 로캘 번역을 시작한 시점입니다. 작업이 `queued` 상태를 벗어나면 설정됩니다.
`completedAt`	작업이 최종 상태에 도달한 시점입니다. `status`가 `completed`, `completed_with_warnings` 또는 `failed`가 되면 설정됩니다.
`steps`	단계별 실행 기록입니다. 항상 `localize` 단계가 포함되며, 활성화된 선택적 pipeline 단계마다 항목이 하나씩 추가됩니다. 전체 기록 구조는 Observe pipeline runs에서 확인하세요.

작업이 끝나기 전까지 outputData는 null입니다

status가 queued 또는 processing인 동안에는 outputData가 비어 있고 errorMessage는 null이므로 아직 읽을 내용이 없습니다. status가 completed 또는 completed_with_warnings에 도달한 뒤에만 outputData를 읽으세요. failed인 경우에는 대신 errorMessage를 읽어야 합니다. 먼저 status로 분기한 뒤 페이로드를 다루세요.

작업 상태 값#

작업은 queued에서 processing로 이동한 뒤, 정확히 하나의 최종 상태에 도달합니다. 다른 무엇보다 먼저 status를 기준으로 분기하세요. 어떤 필드가 채워지는지 알려주는 값입니다.

상태	의미	확인할 항목
`queued`	수락되었지만 아직 시작되지 않았습니다.	아직 없습니다. 폴링하거나 webhook을 기다리세요.
`processing`	엔진이 이 로캘을 번역 중입니다.	아직 없습니다.
`completed`	번역이 완료되었고, 활성화된 모든 단계가 성공했습니다.	`outputData`.
`completed_with_warnings`	번역은 완료되어 `outputData`도 준비되었지만, 치명적이지 않은 pipeline 단계 하나가 완료되지 않았습니다.	먼저 `outputData`, 다음으로 `warnings`.
`failed`	이 작업은 번역 결과를 생성하지 못했습니다.	`errorMessage`.

completed_with_warnings도 번역 결과는 제공합니다

completed_with_warnings는 단순한 경고성 실패가 아닙니다. 전체 outputData를 그대로 받게 되며, 이는 핵심 번역 단계가 성공했다는 뜻입니다. 달라진 점은 치명적이지 않은 단계(예: pre-edit 또는 back-translation)가 완료되지 않았고, 각 실패가 warnings에 { step, message }로 기록된다는 점뿐입니다. 출력은 사용 가능한 결과로 보고, warnings는 번역을 검토하는 사람에게 보여줄 만한 품질 신호로 취급하세요. 번역 결과 자체가 전혀 없는 상태는 오직 failed뿐입니다.

알 수 없는 상태 값 처리하기

위 다섯 가지 상태 값이 현재 기준 계약입니다. 다만 pipeline 단계는 계속 발전하므로 status는 열린 집합으로 다뤄야 합니다. 알고 있는 값으로 분기하고, 예상치 못한 값은 outputData가 있으면 읽고 없으면 로그를 남기는 기본 처리로 보내세요. 대체 처리 없는 switch는 새 상태가 추가되는 날 바로 깨지는 코드가 됩니다.

steps 배열#

steps[]는 단일 작업의 단계별 추적 기록입니다. 엔진이 실행한 각 단계마다 순서대로 하나의 기록이 들어 있습니다. 모든 작업에는 최소한 localize 단계가 포함됩니다. 핵심 번역은 항상 실행되기 때문입니다. 활성화한 각 선택적 pipeline 단계는 기록을 하나씩 더 추가합니다. 따라서 추가 단계가 없는 작업은 localize 단계 하나만 보이고, pre-edit와 back-translation이 활성화된 작업은 세 개의 기록이 보입니다.

이 덕분에 작업은 블랙박스가 아니라 추적 가능한 기록이 됩니다. 어떤 단계가 실행됐는지 그저 믿을 필요가 없습니다. 기록을 직접 읽으면 됩니다. 어떤 단계였는지(stepId), completed했는지, failed했는지, 또는 skipped되었는지, 비용은 얼마였는지(costUsd), 언제 시작해 언제 끝났는지까지 확인할 수 있습니다. 사람 검토 단계의 경우 externalRef*가 외부 기록을 가리킵니다.

json

"steps": [
  {
    "stepId": "preEdit",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0012,
    "createdAt": "2026-03-16T10:30:01.000Z",
    "completedAt": "2026-03-16T10:30:02.000Z"
  },
  {
    "stepId": "localize",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0184,
    "createdAt": "2026-03-16T10:30:02.000Z",
    "completedAt": "2026-03-16T10:30:05.000Z"
  }
]

여기서 failed 항목이 있다고 해서 작업 전체가 반드시 실패하는 것은 아닙니다. 치명적이지 않은 단계가 실패하면 해당 steps[] 기록은 failed로 표시되고, 같은 실패가 작업의 최상위 warnings에도 나타나지만, 작업은 여전히 전체 outputData와 함께 completed_with_warnings에 도달합니다. 전체 기록 구조, 즉 모든 필드와 모든 stepId, 그리고 completed/failed/skipped의 의미는 하나의 기준 페이지인 Observe pipeline runs에 정리되어 있습니다. 이 페이지는 작업에서 그 정보를 어디서 찾는지 보여주고, 그 페이지는 그 구조 자체를 정의합니다.

완료된 작업 읽기#

일반적인 소비자는 status를 기준으로 분기하고, 성공 시 outputData를 기록하며, 실패 시 errorMessage를 로그에 남깁니다. 아래의 그대로 복사해 실행할 수 있는 호출은 위에 표시된 페이로드를 반환합니다.

javascript

const jobId = "ljb_A1b2C3d4E5f6G7h8";
const response = await fetch(`https://api.lingo.dev/jobs/localization/${jobId}`, {
  headers: { "X-API-Key": process.env.LINGO_API_KEY },
});

const job = await response.json();

switch (job.status) {
  case "completed":
  case "completed_with_warnings":
    // outputData is populated; warnings may carry non-critical stage failures
    await db.content.update({
      where: { id: job.outputData.id },
      data: { [`content_${job.targetLocale}`]: job.outputData },
    });
    if (job.warnings.length) console.warn(job.targetLocale, job.warnings);
    break;
  case "failed":
    console.error(`${job.targetLocale} failed: ${job.errorMessage}`);
    break;
  default:
    // queued or processing - nothing to read yet; also catches future states
    break;
}

폴링 vs 푸시

이 엔드포인트는 특정 시점의 상태를 읽는 용도입니다. 대부분의 작업에서 엔진은 로캘당 2~8초 정도 걸리므로, 폴링한다면 2초 간격으로 시작하는 것이 무난합니다. 폴링을 완전히 피하려면 webhook을 등록해 해당 로캘이 완료됐다는 알림을 받을 때만 작업을 조회하거나, WebSocket으로 전체 그룹을 지켜보세요. 어느 쪽이든 여기서 확인하는 최종 GET가 outputData의 기준이 되는 읽기입니다.

이 엔드포인트가 알 수 없는 jobId나 누락된 키 같은 오류를 반환할 경우, 표준 JSON 오류 모델을 따릅니다. 자세한 내용은 Errors and status codes를 참고하세요.

다음 단계#

작업 그룹 추적

모든 로캘 전반의 집계 수치를 확인하고 부분 실패를 처리합니다

작업 목록

커서 페이지네이션으로 작업을 조회하고 상태 또는 엔진별로 필터링합니다

실시간 진행 상황(WebSocket)

폴링 없이 각 작업이 완료될 때마다 로캘별 상태를 확인합니다

한 로캘의 번역 결과와 생성 과정의 단계별 기록을 확인합니다.

text

GET /jobs/localization/:jobId

비동기 로컬라이제이션이 처음이신가요? 개요부터 시작하세요.

인증#

응답#

json

{
  "id": "ljb_A1b2C3d4E5f6G7h8",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "targetLocale": "de",
  "status": "completed",
  "outputData": {
    "id": "course_101",
    "title": "Einführung in maschinelles Lernen",
    "steps": [
      { "heading": "Was ist ML?", "body": "Maschinelles Lernen ist ein Teilbereich der künstlichen Intelligenz." },
      { "heading": "Überwachtes Lernen", "body": "Trainieren eines Modells mit gelabelten Daten." }
    ],
    "metadata": { "author": "Dr. Smith", "difficulty": "beginner" }
  },
  "errorMessage": null,
  "warnings": [],
  "callbackStatus": "delivered",
  "createdAt": "2026-03-16T10:30:00.000Z",
  "startedAt": "2026-03-16T10:30:01.000Z",
  "completedAt": "2026-03-16T10:30:04.000Z",
  "steps": [
    {
      "stepId": "localize",
      "type": "action",
      "status": "completed",
      "errorMessage": null,
      "externalRefType": null,
      "externalRefId": null,
      "externalRefUrl": null,
      "createdAt": "2026-03-16T10:30:01.000Z",
      "startedAt": "2026-03-16T10:30:01.000Z",
      "completedAt": "2026-03-16T10:30:04.000Z"
    }
  ]
}

필드	설명
`id`	이 작업 자체의 ID(`ljb_…`)입니다. 경로에 전달한 바로 그 값입니다.
`groupId`	이 작업이 속한 상위 job group(`ljg_…`)입니다. 모든 형제 로캘을 한 번에 보려면 job-group 엔드포인트에 전달하세요.
`targetLocale`	이 작업이 번역한 대상 BCP-47 로캘입니다. 대상 로캘마다 작업이 하나씩 존재합니다. `outputData`를 올바른 열이나 파일로 라우팅할 때 기준이 되는 필드입니다.
`status`	`queued`, `processing`, `completed`, `completed_with_warnings` 또는 `failed`입니다.
`outputData`	입력 구조와 일치하는 번역된 콘텐츠입니다. `status`가 `completed` 또는 `completed_with_warnings`일 때 제공됩니다.
`errorMessage`	오류 설명입니다. `status`가 `failed`일 때 제공되며, 그 외에는 `null`입니다.
`warnings`	치명적이지 않은 pipeline 단계 실패입니다. 각 항목은 `{ step, message }`입니다. `status`가 `completed_with_warnings`인 경우가 아니면 비어 있습니다.
`callbackStatus`	Webhook 전송 상태입니다: `pending`, `delivered` 또는 `failed`. 콜백 URL이 설정되어 있지 않으면 `null`입니다.
`createdAt`	작업이 수락된 시점입니다(작업을 생성한 `202`의 타임스탬프).
`startedAt`	엔진이 이 로캘 번역을 시작한 시점입니다. 작업이 `queued` 상태를 벗어나면 설정됩니다.
`completedAt`	작업이 최종 상태에 도달한 시점입니다. `status`가 `completed`, `completed_with_warnings` 또는 `failed`가 되면 설정됩니다.
`steps`	단계별 실행 기록입니다. 항상 `localize` 단계가 포함되며, 활성화된 선택적 pipeline 단계마다 항목이 하나씩 추가됩니다. 전체 기록 구조는 Observe pipeline runs에서 확인하세요.

작업이 끝나기 전까지 outputData는 null입니다

작업 상태 값#

상태	의미	확인할 항목
`queued`	수락되었지만 아직 시작되지 않았습니다.	아직 없습니다. 폴링하거나 webhook을 기다리세요.
`processing`	엔진이 이 로캘을 번역 중입니다.	아직 없습니다.
`completed`	번역이 완료되었고, 활성화된 모든 단계가 성공했습니다.	`outputData`.
`completed_with_warnings`	번역은 완료되어 `outputData`도 준비되었지만, 치명적이지 않은 pipeline 단계 하나가 완료되지 않았습니다.	먼저 `outputData`, 다음으로 `warnings`.
`failed`	이 작업은 번역 결과를 생성하지 못했습니다.	`errorMessage`.

completed_with_warnings도 번역 결과는 제공합니다

알 수 없는 상태 값 처리하기

steps 배열#

json

"steps": [
  {
    "stepId": "preEdit",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0012,
    "createdAt": "2026-03-16T10:30:01.000Z",
    "completedAt": "2026-03-16T10:30:02.000Z"
  },
  {
    "stepId": "localize",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0184,
    "createdAt": "2026-03-16T10:30:02.000Z",
    "completedAt": "2026-03-16T10:30:05.000Z"
  }
]

완료된 작업 읽기#

javascript

const jobId = "ljb_A1b2C3d4E5f6G7h8";
const response = await fetch(`https://api.lingo.dev/jobs/localization/${jobId}`, {
  headers: { "X-API-Key": process.env.LINGO_API_KEY },
});

const job = await response.json();

switch (job.status) {
  case "completed":
  case "completed_with_warnings":
    // outputData is populated; warnings may carry non-critical stage failures
    await db.content.update({
      where: { id: job.outputData.id },
      data: { [`content_${job.targetLocale}`]: job.outputData },
    });
    if (job.warnings.length) console.warn(job.targetLocale, job.warnings);
    break;
  case "failed":
    console.error(`${job.targetLocale} failed: ${job.errorMessage}`);
    break;
  default:
    // queued or processing - nothing to read yet; also catches future states
    break;
}

폴링 vs 푸시

다음 단계#

작업 그룹 추적

모든 로캘 전반의 집계 수치를 확인하고 부분 실패를 처리합니다

작업 목록

커서 페이지네이션으로 작업을 조회하고 상태 또는 엔진별로 필터링합니다

실시간 진행 상황(WebSocket)

폴링 없이 각 작업이 완료될 때마다 로캘별 상태를 확인합니다