ローカライゼーションジョブを作成

ローカライゼーションジョブグループを作成します。1回のリクエストで、指定したすべての対象ロケールにコンテンツを展開できます。

文字列のペイロードとロケールの一覧があり、それらをまとめて翻訳したい。でも、ロケールごとに振り分ける処理は自前で実装したくない。そんなときは POST /jobs/localization です。ペイロード全体と最大100件の対象ロケールを1回のリクエストで受け取り、202 Accepted を即座に返します。返ってくるのはグループIDと、ロケールごとに1件のジョブ。1回のリクエストで、すべてのロケールへ。ジョブの作成はプラットフォームが行い、それぞれを独立して処理します。

POST /jobs/localization

このページでは、作成エンドポイントの呼び出し方法を説明します。パラメータ、リクエストの形式、202 レスポンス、そして安全に再試行できるようにする方法までをカバーします。非同期ローカライゼーションが初めてなら、まずは Async Localization API overview で全体像をつかんでください。グループ作成後に各ロケールのステータスの意味を確認したい場合は、ジョブグループの追跡 を参照してください。

パラメータ#

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 です。文字列は翻訳され、それ以外は型を保ったまま維持されます。文字列であっても翻訳対象から外したい場合（slug、アセット 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 の状態で実行待ちになります。ジョブの進行に応じて各ステータスが何を意味するのか、また1つのロケールだけ失敗して他がそのまま進む場合にどうなるのかは、Track a job group を参照してください。

例#

同じリクエストを Node と Python で示します。どちらも1回の 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 や event handler のような箇所です。つまり、再試行が走ったり重複イベントが届いたりしたときに、同じコードが2回実行されがちな場所です。対策なしでは、2回の呼び出しで2つのジョブグループが作成され、同じコンテンツが2回翻訳キューに入ってしまいます。

idempotencyKey を渡せば、そのリスクはなくなります。同じキーで同じリクエストを2回送ると、プラットフォームは新しいグループを作らず、既存のグループを返します。つまり、2セット目のジョブは作成されません。キーはエンジン単位でスコープされるため、別のエンジンに対して同じキーを使うと別グループになります。

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

1つのペイロードをすべてのロケールへ展開できる POST はこれだけです。しかも、再試行が起こりうる同じコードパスから安全に呼び出せます。groupId は必ず保存してください。追跡やライブ進捗確認で使うのはこの値です。

次のステップ#