로컬라이제이션 작업 생성

로컬라이제이션 작업 그룹을 생성하세요. 요청 한 번이면 지정한 모든 대상 로캘로 콘텐츠를 확장할 수 있습니다.

문자열 페이로드와 로캘 목록은 있는데, 각 로캘로 나눠 보내는 로직까지 직접 구현하고 싶지는 않다면 POST /jobs/localization가 해결해 줍니다. 전체 페이로드와 최대 100개의 대상 로캘을 한 번에 받아, 그룹 ID와 로캘별 작업 하나씩이 포함된 202 Accepted를 즉시 반환합니다. 요청은 한 번, 로캘은 전체. 작업 생성은 플랫폼이 맡고, 각 작업은 서로 독립적으로 처리됩니다.

POST /jobs/localization

이 페이지에서는 생성 호출의 매개변수, 요청 구조, 202 응답, 그리고 재시도해도 안전하게 호출하는 방법을 다룹니다. 비동기 로컬라이제이션이 처음이라면 먼저 비동기 로컬라이제이션 API 개요에서 전체 흐름을 잡아보세요. 그룹이 생성된 뒤 각 로캘 상태가 무엇을 뜻하는지는 작업 그룹 추적에서 확인할 수 있습니다.

매개변수#

sourceLocale, targetLocales, data는 필수입니다. 그 외 항목은 동작을 세부 조정하거나, 같은 호출을 반복해도 더 안전하게 만들어 줍니다.

요청#

data 필드는 단순한 키-값 쌍은 물론, 객체와 배열이 어떤 깊이로 중첩된 구조도 받을 수 있습니다. 엔진은 모든 문자열 값을 번역하고, 문자열이 아닌 값(숫자, 불리언, null)은 그대로 유지한 채, 보낸 것과 정확히 같은 형태로 반환합니다. 즉, 앱에서 이미 저장하고 있는 객체를 그대로 넘기면 됩니다. 평탄화도, 구조 변경도 필요 없습니다.

{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr", "ja"],
  "data": {
    "lesson_title": "Introduction to Machine Learning",
    "lesson_summary": "This lesson covers the fundamentals of ML, including supervised and unsupervised learning."
  },
  "callbackUrl": "https://your-app.com/webhooks/translations",
  "idempotencyKey": "course_101-v3"
}

이 중첩 페이로드에는 번역해야 하는 텍스트와, 절대 바뀌면 안 되는 값(id, course_101, difficulty)이 함께 들어 있습니다. 문자열은 번역되고, 나머지는 타입 그대로 보존됩니다. 문자열도 제외해야 한다면(슬러그, 에셋 URL, enum 코드 등) lockedKeys에 지정하세요. 그러면 각 로캘 출력에 원문 그대로 다시 병합됩니다.

응답 (202 Accepted)#

이 호출은 즉시 반환됩니다. 번역이 끝날 때까지 기다리지 않고, 그룹 ID와 로캘별 작업 ID를 먼저 돌려준 뒤 각 작업은 플랫폼이 백그라운드에서 독립적으로 처리합니다.

{
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "status": "pending",
  "jobs": [
    { "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "queued" },
    { "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "queued" },
    { "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "queued" }
  ],
  "createdAt": "2026-03-16T10:30:00.000Z"
}

로캘 3개를 보내면 작업 3개가 돌아오고, 각 작업은 모두 queued 상태로 실행 준비가 됩니다. 이후 상태가 어떻게 바뀌는지, 또 한 로캘만 실패하고 나머지는 정상적으로 진행될 때 어떻게 해석해야 하는지는 작업 그룹 추적에서 다룹니다.

예제#

같은 요청을 Node와 Python으로 보여줍니다. 둘 다 POST 한 번만 보내고, 202에서 그룹 ID와 작업 수를 바로 읽어옵니다.

const response = await fetch("https://api.lingo.dev/jobs/localization", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.LINGO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceLocale: "en",
    targetLocales: ["de", "fr", "ja"],
    data: {
      title: "Introduction to Machine Learning",
      steps: [
        { heading: "What is ML?", body: "Machine learning is a subset of AI." },
        { heading: "Supervised Learning", body: "Training with labeled data." },
      ],
    },
    callbackUrl: "https://your-app.com/webhooks/translations",
  }),
});

const { groupId, jobs } = await response.json();
// 202 Accepted – the call returns without waiting for translation.
console.log(groupId);     // "ljg_A1b2C3d4E5f6G7h8"
console.log(jobs.length); // 3 – one queued job per target locale

재시도해도 안전하게 호출하기#

이 요청을 호출하기 가장 자연스러운 지점은 save hook이나 이벤트 핸들러입니다. 공교롭게도 바로 이런 코드가 재시도나 중복 이벤트 때문에 두 번 실행되기 쉽습니다. 보호 장치가 없다면 호출 두 번은 작업 그룹 두 개가 되고, 같은 콘텐츠가 번역 대기열에 두 번 들어갑니다.

idempotencyKey를 함께 보내면 그 위험을 없앨 수 있습니다. 같은 키로 동일한 요청을 두 번 보내면 플랫폼은 새 그룹을 만들지 않고 기존 그룹을 반환합니다. 즉, 두 번째 작업 세트는 생기지 않습니다. 키는 엔진별로 범위가 적용되므로, 같은 키라도 다른 엔진으로 보내면 다른 그룹으로 처리됩니다.

const key = `${content.id}-v${content.version}`;

async function submit() {
  const response = await fetch("https://api.lingo.dev/jobs/localization", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sourceLocale: "en",
      targetLocales: ["de", "fr", "ja", "ko", "pt-BR"],
      data: { title: content.title, steps: content.steps },
      callbackUrl: "https://your-app.com/webhooks/translations",
      idempotencyKey: key,
    }),
  });
  return (await response.json()).groupId;
}

const first = await submit();
const again = await submit(); // same key – duplicate submission
console.log(first === again); // true – same group returned, no second set of jobs

POST 한 번이면 페이로드를 모든 로캘로 확장할 수 있고, 재시도가 걸릴 수 있는 같은 코드 경로에서도 안심하고 호출할 수 있습니다. groupId는 꼭 저장해 두세요. 추적과 실시간 진행 상태 확인으로 이어지는 기준 값입니다.

다음 단계#