1つ以上のコンポーネントスキーマに含まれる、公開済みのすべてのドキュメントを、指定した対象言語へバックグラウンドで翻訳するキューに追加します。各翻訳が完了すると、結果は translations テーブルにアップサートされます。

エンドポイント: POST /translation 認証: Bearer JWT（WorkOS）

リクエストボディ

{
  "websiteId": "<uuid>",
  "schemaNames": ["post", "hero"],
  "languages": ["fr", "es", "de"]
}

* schemaNames または schemaName のいずれかを指定してください。

公開済みコンテンツが null ではない公開済みドキュメントのみが対象となります。

レスポンス

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es", "de"],
  "status": "queued",
  "documents_processed": 12,
  "translations_scheduled": 30,
  "translations_skipped": 6,
  "translations_completed": 0,
  "translations_failed": 0,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:00:00Z"
}

返されるステータス:

• 翻訳がキューに追加された場合は 202 Accepted
• すべての翻訳がすでに最新の場合は 200 OK
• 同一のリクエストがすでに実行中の場合は既存のアクティブなジョブ

ジョブステータスとして次の値が使用されます:

• preparing
• queued
• running
• completed
• completed_with_errors
• failed

最新の翻訳をスキップする

各ドキュメントと言語の組み合わせには、ソースドキュメントの公開済みコンテンツの SHA-256 ハッシュが保存されます。

保存されているソースハッシュが現在の公開済みコンテンツと一致する場合、翻訳はスキップされます。これにより、内容が変更されていない場合は再翻訳せずにエンドポイントを繰り返し呼び出せます。

同等のジョブがアクティブな間に公開済みコンテンツが変更された場合、サービスは新しいリクエストを拒否します。アクティブなジョブの完了後に再度送信してください。

処理動作

翻訳は初回レスポンスの後に非同期で実行されます。

• 処理は同時実行数を制限して行われます。
• 一時的な失敗はバックオフを使用して再試行されます。
• 成功した結果は完了するたびに保存されます。
• 個別の推論または保存の失敗はジョブに記録されます。
• 一部が成功したジョブは completed_with_errors で終了します。

例

curl -X POST '{TRANSLATION_API_URL}/translation' \
  -H 'Authorization: Bearer <workos-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "<uuid>",
    "schemaNames": ["post", "hero"],
    "languages": ["fr", "es"]
  }'

エラー

• 400 Bad Request — スキーマまたは言語が指定されていない、サポートされていない言語である、またはバッチが設定された上限を超えている
• 401 Unauthorized — bearer トークンがない、または無効である
• 409 Conflict — 一致する処理がアクティブだが、公開済みのソースコンテンツが変更されている
• 500 Internal Server Error — ソースドキュメントを準備できない、またはデータベース操作に失敗した

翻訳ジョブを取得する

翻訳ジョブの最新の進捗を取得します。

エンドポイント: GET /translation-jobs/{job_id} 認証: Bearer JWT（WorkOS）

レスポンス

レスポンスには、POST /translation で返されるものと同じジョブオブジェクトが使用され、ステータスと進捗カウントが更新されます。

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es"],
  "status": "running",
  "documents_processed": 12,
  "translations_scheduled": 24,
  "translations_skipped": 0,
  "translations_completed": 16,
  "translations_failed": 1,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:01:30Z"
}

例

curl '{TRANSLATION_API_URL}/translation-jobs/<job-id>' \
  -H 'Authorization: Bearer <workos-jwt>'

エラー

• 401 Unauthorized — bearer トークンがない、または無効である
• 404 Not Found — ジョブが存在しない、または保持期間を過ぎている

翻訳ジョブは現在メモリ内に保持されています。翻訳サービスが再起動するとジョブステータスは失われ、複数インスタンスでのデプロイではスティッキールーティングが必要です。