你的内容在不断变化，而现在，它必须覆盖你支持的每个语言区域。培训模块新增了一课。CMS 条目刚被保存。产品描述被编辑。翻译需要同时分发到德语、法语、日语以及十几种其他语言——而你的应用不该因此卡住。
异步本地化 API 正是为这一刻而生：一次请求，覆盖所有语言区域，结果随完成陆续返回。 你只需把内容和目标语言区域一起 POST 一次，就能立刻拿到一个 202；随后平台会将每个语言区域的翻译作为独立的后台任务处理。你的术语表、品牌语调和模型配置都能保留——底层仍是 同步 API 使用的同一套引擎——而你不必再自己扛重试。
本页内容
问题是什么#
培训平台、内容管理系统和在线学习工具，往往需要在内容创建或更新的第一时间，把它翻译成几十种语言。同步本地化 API 能胜任这件事，但一旦规模上来，你就得做取舍。
比如，一个用英语编写的培训模块需要覆盖 14 种语言。使用同步 API 时，你有两个选择，但每个都有代价：
并行发起 14 个请求——每个目标语言区域一个请求，而且每个请求都带着同样的源内容。这样你可以在各语言返回后立即渲染，但你得管理 14 次网络往返和重复数据；只要其中一个失败，重试逻辑也得你自己处理。
在一次同步调用中翻译全部 14 种语言——网络往返更少，但你必须等最慢的那个语言区域完成，才能展示其中任何一个结果。
无论选哪条路，翻译处理期间你的应用都会被牵住手脚。如果服务器中途重启，进行中的翻译就没了。如果某个语言失败，部分失败怎么处理也得你自己收拾。而且这两种方式都无法给用户一个清晰信号：翻译正在进行中。
异步 API 消除了这种取舍。一次请求就会创建一个任务组，其中每个目标语言区域对应一个任务。每个任务都会以持久化后台工作流的方式，独立通过你的本地化引擎运行——所以即使你的服务器重启，也不会丢任何进度，因为这些工作根本不跑在你的进程里。每个语言区域一完成，结果就会立刻按语言区域交付。你的应用保持响应。失败彼此隔离。平台负责重试和交付。
只有一个语言区域，而且能等一秒？那就用同步。
当你面对的是多个语言区域、较长内容，或者需要在 UI 中展示进度时，异步 API 才真正能体现价值。如果你只需要一个语言对，并且可以接受一次网络往返的等待，那么 同步 Localize 端点 会是更简单的选择——一次请求，响应里直接带回翻译结果，也不用部署 webhook 端点。当任务太大、太慢，或者目标语言区域太多、不适合阻塞等待时，就该用异步。
它如何工作#
总共三步，而且只有第一步发生在你的请求/响应周期里。后面两步都由平台按自己的节奏完成。
提交一次请求
把你的内容和目标语言区域 POST 到 /jobs/localization。API 会校验载荷，创建一个“每个语言区域一个任务”的任务组，并返回 202，其中包含 group ID 和任务摘要。你的应用可以立刻继续往下走——翻译不会在这次调用里执行。完整的请求和响应结构，请参见 Create jobs。
平台独立处理每个语言区域
每个结果一落地就接收
某个语言区域一完成，平台就会把结果发送到你的 webhook URL。如果你想在 UI 里展示实时进度——比如一个会随着任务完成不断更新的“14 个里已完成 3 个”计数器——可以连接到该任务组的 WebSocket。如果你更倾向于主动拉取，也可以按固定间隔 轮询该任务组。
认证
每个请求——无论 REST 还是 WebSocket——都通过你的 X-API-Key 请求头完成认证。密钥以组织为作用域，可访问该组织下的所有引擎。详情请参见 Authentication，创建密钥请参见 API Keys。
任务组模型#
一次提交会生成一个 group，其中每个目标语言区域对应一个 job。这就是整个心智模型，也是它能回答那些棘手问题的关键。
细心的读者此刻大概已经在心里列清单了：如果某个语言区域失败会怎样？而在这些任务进行期间，我的应用会发生什么？任务组模型同时回答了这两个问题。
- 失败彼此隔离，因为每个语言区域都是独立任务。 如果德语成功、日语失败，德语翻译会照常交付，而日语任务会带上它自己的
errorMessage。任务组会报告为partial，而已经成功的部分仍然可以上线。一个语言区域的失败，不会回滚另一个已经完成的语言区域。完整的状态语义请参见 Track a job group。 - 进行中的任务在重启后依然存在，因为它根本不跑在你的进程里。 每个任务都是平台上的持久化后台工作流。即使你的服务器重启，进行中的内容也不会丢——你只需重新连接或轮询，任务组仍会停留在你上次离开时的状态。
- 任务组本身就是一个可直接接到 UI 上的进度模型。 保存来自
202的groupId，然后通过 webhook 交付或 WebSocket 快照驱动进度指示器。“14 种语言里已完成 3 种”本质上就是对任务组子任务的计数。
这个模型的真实成本在于：你需要承担一点同步调用不要求的集成工作。为了接收结果，你需要部署一个 HTTPS webhook 端点，或者维持一个服务端 WebSocket 连接；同时，你要在每个语言区域结果到达时分别处理，而不是像以前那样直接从单个响应里读取翻译数据。作为交换，平台负责重试、失败隔离和结果交付——而你的应用永远不会被翻译阻塞。
这正是异步 API 要做出的取舍：一次请求，覆盖所有语言区域，结果随完成陆续返回。 接下来的页面，就是这句话里各个动作的展开。
