POST /translation

启动将某个架构的已发布文档批量后台翻译为目标语言。

将来自一个或多个组件架构的所有已发布文档排入后台翻译队列，以翻译到一组目标语言。每个翻译完成后，其结果会被插入或更新到 translations 表中。

端点： POST /translation 认证： Bearer JWT（WorkOS）

请求正文

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

字段	类型	必填	说明
`websiteId`	uuid	yes	包含源文档的网站。
`schemaNames`	string[]	yes*	要翻译的组件架构。重复的名称会被移除。
`schemaName`	string	yes*	提交单个架构的传统替代方案。
`languages`	string[]	yes	受支持的目标语言代码。重复的代码会被移除。

* 请提供 schemaNames 或 schemaName 之一。

只有具有非空已发布内容的已发布文档才会被考虑。

响应

{
  "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 当所有翻译都已是最新时
当相同请求已经在运行时，返回现有的活动作业

字段	描述
`job_id`	用于获取作业进度的标识符。
`status`	当前作业状态。
`documents_processed`	找到的符合条件的源文档数量。
`translations_scheduled`	排队的文档语言对数量。
`translations_skipped`	因源哈希仍然最新而被跳过的数量。
`translations_completed`	成功翻译的数量。
`translations_failed`	失败的数量。
`reused`	响应是否指向现有的活动作业。

可能的作业状态包括：

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 — 作业不存在或不再保留

翻译作业目前保存在内存中。翻译服务重新启动时，作业状态会丢失，多实例部署需要粘性路由。

Previous‹PATCH /dataset/{schema_name}NextPATCH /translations›