人工审核 API
以授权审核者的身份查找待处理的文档目标、批准翻译并提交修改。
每次审核针对一份文档的一种目标语言。当配置的人工审核阶段中有符合条件的单元等待决策时,审核即可开始。请在启动任务前配置决策池路由。
发起审核请求需要组织访问权限,以及审核该引擎翻译的权限。决策请求还必须由个人发起:请使用审核者的会话访问令牌或个人 API 密钥进行身份验证。组织服务密钥不能用于提交人工决策。
查找审核 #
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50响应为 { "data": [...], "meta": { "nextCursor": "..." } }。使用游标继续获取后续页面,直到 nextCursor 为 null。
| 查询字段 | 取值和默认值 |
|---|---|
statuses | open、completed、timedOut、cancelled;默认为 open。如需指定多个值,请重复传入该参数。 |
order | oldest(默认)或 newest。 |
limit | 1–100;默认为 50。 |
cursor | 上一页返回的不透明游标。请保持筛选条件和排序不变。 |
查询已作出决策的状态需要管理组织审核的权限。每条摘要均包含 documentId、locale、jobId、engineId、engineName、documentKey、sourceLocale、provider、vendorStartedAt、status、readyAt、expiresAt、closedAt、totalUnits 和 pendingUnits。
读取单条审核 #
GET /v2/localization/documents/:documentId/targets/:locale/review响应包含相同的目标和引擎上下文,还包含 units、接管信息以及已记录的外部订单(如有)。在有人接管之前,takeover 为 null;未记录订单时,externalOrder 可能不存在或为 null。每个单元包含 unitId、key、position、source、value、reference、quality、eligibility、result、decision、reviewerId 和 decidedAt。
使用 sourceText 显示原文,使用 valueText 初始化编辑内容。作出决策后,显示 settledText:它包含已接受的修改或其他已确定的结果,而 valueText 保留审核前的翻译。在结果可用之前,settledText 等于 valueText。
quality 是质量关卡针对该单元的输出,其值为流水线参考中所述的 { "findings": [...] };若质量关卡未检查该单元,则为 null。eligibility 为 required、qualityPassed、localeNotCovered 或 reused。只有尚未作出决策且必须审核的单元才需要人工决策,其他单元仅提供上下文。非空且已确定的 result 可能表示超时或回退结果;请检查 decision,以确认是否有人批准或修改了该单元。
value 是进入审核时的翻译。它可以是字符串,也可以是由结构化文本、变量和标记片段组成的数组。编辑时请保留占位符的标识和嵌套结构。
批准或编辑 #
批准所有剩余的必须审核单元,不作修改:
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-all此请求没有请求体。若要作出明确决策,请向 /decisions 发送 POST 请求,提交一个非空数组,其中的单元 ID 必须唯一:
{
"decisions": [
{ "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
{ "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
]
}请使用获取到的审核中的 ID。若要编辑结构化值,请以其 valueText 为基础,将编辑后的文本作为 Edited.value 发送。例如,Hello {name}<C1>world</C1><C2/> 可以改为 Bonjour {name}<C1>tout le monde</C1><C2/>。请保留占位符令牌、各令牌的数量以及标记的嵌套结构;同级占位符可以调整位置。结构化文本中的字面分隔符使用实体转义。API 会将此文本解析回结构化片段。您也可以直接提交结构化片段数组。修改纯字符串 ICU 内容时,必须保留译文中的本地化分支和数量。
请求成功后会返回更新后的审核。内部审核者可以只提交部分必须审核的单元。决策一经确定便不可更改。只要目标仍接受决策,同一审核者重复提交相同内容时就会复用已保存的决策;有冲突的决策会被拒绝。在写入任何决策之前,系统会先验证整组提交内容。
LocalizationReviewInvalid(422)表示提交无效,包括占位符被更改的情况。LocalizationReviewClosed(409)表示该审核或某个单元已无法接受此决策。目标完成后重试,即使首次提交成功,也可能返回 409。如果响应丢失,请获取审核并比对已保存的决策和审核者 ID,再确定还需要完成哪些操作。
外部审核与接管 #
读取 GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status 可了解外部服务提供方的当前状态:unstarted、inProgress、completed 或 unknown。
接管外部审核时,必须在一次提交中为所有剩余的必须审核单元作出决策。这会关闭外部审核,并尝试取消服务提供方的订单。已经开始的工作仍可能产生费用。供应商状态可能在读取和提交之间发生变化,因此不能保证免费取消。
等待最终文件 #
审核截止时间为 expiresAt,根据 readyAt 计算。轮询和重试不会延长该期限。超时后,尚未作出决策的单元会保留此前的翻译并附带警告;已接受的决策保持不变。
审核结束后,流水线的后续阶段仍可能更改文本。请获取任务并下载其已完成的目标,以取得最终文件。审核完成并不意味着最终下载结果已经生成。