グループを作成して groupId を受け取り、いま複数のロケールで翻訳が並行して進んでいる。そんなとき、処理が落ち着くまで繰り返し知りたいことは1つだけです。この送信全体はいまどうなっているのか。ロケールごとではなく、全体の集計として。完了はいくつか、警告付きで出力されたものはいくつか、失敗はいくつか、まだ実行中はいくつか。
このエンドポイントが返すのは、まさにその答えです。1回ポーリングするだけで、すべてのロケールのステータスを1つのレスポンスで取得できます。非同期ローカライゼーションが初めてなら、まずは Async Localization API overview からどうぞ。
このページの内容
ジョブグループを取得#
ジョブグループと、その配下にあるすべての子ジョブのステータスを取得します。
GET /jobs/localization/groups/:groupIdX-API-Key ヘッダーに API キーを指定して認証します。使用するのは、グループを作成 したときと同じキーです。groupId には、202 レスポンスで返された ljg_ プレフィックス付きの ID を指定します。
レスポンス#
レスポンスは、送信全体のスナップショットです。グループ自身の status、4つの件数、そしてそれぞれの状態を持つ子ジョブが含まれます。ポーリングのたびに確認するのは、このオブジェクトです。
{
"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"
}終端状態にあるジョブの3つの件数フィールド、つまり completedJobs、completedWithWarningsJobs、failedJobs を合計すると、完了したロケール数になります。残りの totalJobs は、まだ queued か processing の状態です。上のスナップショットでは、3件中1件が完了し、2件はまだ進行中です。つまり jobs 配列を見なくても、件数を1回読むだけで、処理がまだ落ち着いていないことがわかります。この合計が totalJobs に達したとき、グループは終端ステータスに到達しています。
各ジョブの warnings 配列には、重大ではない pipeline ステージの失敗が現れます。たとえば、事前編集や逆翻訳のステップがスキップされたような場合です。配列が空でなければ、そのジョブは出力自体は生成しているものの、少なくとも1つの任意ステージが完了していないことを意味します。翻訳済みの outputData 自体は 単一ジョブ にあります。完了したロケールの内容を確認する段階になったら、そちらを取得してください。
グループステータス#
グループの status は、子ジョブ全体を1つの値に集約したものです。終端状態になるまでポーリングします。
| グループステータス | 意味 |
|---|---|
pending | グループは作成済みで、まだどのジョブも開始されていない |
processing | 少なくとも1つのジョブが進行中 |
completed | すべてのジョブが正常に完了 |
completed_with_warnings | すべてのジョブで出力は生成されたが、少なくとも1つのジョブで1つ以上の任意の pipeline ステージが失敗した |
partial | 完了したジョブと失敗したジョブが混在している |
failed | すべてのジョブが失敗 |
completed、completed_with_warnings、partial を分けていることこそ、このエンドポイントの要点です。これにより、「すべてのロケールが配信された」「すべてのロケールが配信されたが、一部に警告がある」「一部のロケールは配信され、一部はされなかった」を区別できます。そうでなければ、各ジョブを読んで自分で組み立て直すしかありません。partial はエラーではなく、実際に起きている状態そのものです。グループがそれをそのまま返してくれるので、コード側で素直に分岐できます。
ポーリング頻度#
ポーリング間隔
ほとんどのジョブでは、処理に1言語あたり 2〜8 秒かかります。webhook や WebSocket を使わずにポーリングするなら、まずは 2 秒間隔から始めるのが現実的です。
グループを追跡する方法として、いちばんシンプルなのはポーリングです。短時間で終わるバッチなら、それでまったく問題ありません。ただし、より弱い選択肢であることも確かです。変化があってもなくても毎回往復通信が発生し、ロケールの完了を知るのは完了した瞬間ではなく、次のポーリング時点になります。
各結果を準備できた瞬間に受け取りたいなら、ポーリングするのではなく、通知を受けるべきです。プラットフォームは、完了した各ロケールをその時点であなたの webhook URL に配信します。また、グループに対する WebSocket connection は、変更のたびに完全な状態スナップショットをプッシュするので、UI は問い合わせなしで更新されます。webhook エンドポイントや永続接続を用意する手間がジョブに見合わないならポーリング、UI への遅延が重要ならプッシュを選んでください。
1つのロケールが失敗したとき#
「一度に多くのロケールへ翻訳する」と聞くと、まず気になるのは当然この点です。1つのロケールが失敗したら、残りはどうなるのか。その答えはレスポンスにあります。
各ロケールは独立したジョブです。たとえばドイツ語が成功し、日本語が失敗しても、ドイツ語の翻訳は完了し、通常どおり配信されます。失敗したからといってロールバックされることはありません。失敗したジョブはグループ内で 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"
}2つのロケールは配信され、1つはされなかった。そのことが、細かく見て回らなくても件数だけでわかります。再試行するには、新しいリクエストを送信 し、失敗したロケールだけを対象に、新しい冪等キーを使ってください。失敗したロケールの完全なエラー説明、つまり errorMessage は 単一ジョブ にあります。グループが返すのは、件数と最終判断です。
部分的な失敗は正常な状態
partial は、件数が示すとおりの意味です。完了したロケールもあれば、失敗したロケールもあります。完了したロケールはすでに配信済みです。ロールバックするものはなく、成功したロケールに対して再度コストをかける必要もありません。再試行するのは失敗したものだけです。
