waafir-translate 参考
waafir-translate 服务器以两种形式向已连接的 AI 客户端提供 Waafir 的翻译功能:
translate_text— 一段文本片段,以内联、同步方式翻译。translate_file/translate_file_status— 数据室中的整个文档,由与 AI 翻译产品功能相同的、保留版式的流水线进行翻译。
连接:https://app.waafir.io/api/mcp/waafir,或领域服务器 https://app.waafir.io/api/mcp/waafir-translate;两者上的工具名称相同,请参阅设置。translate_text 和 translate_file_status 需要 read 权限范围(或更高)的 PAT;translate_file 需要 write,因为启动文档翻译会创建持久记录,并消耗付费的翻译算力。
translate_text
将一段短文本翻译为目标语言。该调用是同步的,输入文本、输出文本。省略源语言即可自动检测;返回结果中会包含检测到的(或您提供的)源语言,以便您确认。
输入
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | string | 是 | 要翻译的文本,1–10,000 个 UTF-8 字节。 |
target_lang | string | 是 | 目标语言代码,例如 fr、ar、es。 |
source_lang | string | 否 | 源语言代码。省略则自动检测。 |
输出
{ translated_text, detected_source_lang }translated_text— 以目标语言呈现的文本。detected_source_lang— 实际使用的源语言:即您提供的语言,或在省略source_lang时自动检测到的语言。
要求:付费套餐,且您组织的 AI 功能已启用(默认开启;组织管理员可以在 设置 → AI 与集成 中将其关闭)。当您的组织达到每日 AI 用量上限,或 Waafir 暂停了该功能时,调用也会被拒绝;错误消息会说明是哪种情况。
大小限制
由于该工具是同步路径,每次调用的 text 限制为 10,000 个 UTF-8 字节。超出该限制的输入会返回明确的错误,而不会被静默截断。对于更大的内容(整个文档),请使用文档翻译功能,它专为文件而设计,并会保留文件的版式。
translate_file
开始翻译数据室中的整个文档。文档翻译是异步的:作业一进入队列,此调用就会返回,您需要轮询 translate_file_status 获取结果。
输入
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_id | string | 是 | 文件的 UUID。 |
target_lang | string | 是 | 目标语言代码,必须是产品支持文档翻译的 28 种语言之一。 |
retry | boolean | 否 | 重新运行先前失败的翻译。对于已完成或进行中的翻译,此参数会被忽略。 |
输出
{ file_id, target_lang, language_name, status, enqueued,
previous_status, delete_with, note? }status—queued、in_progress、already_translated或failed。enqueued— 本次调用是否真正启动了工作。请务必检查:该工具不会重新运行已完成或正在进行的翻译,因此第二次调用会返回enqueued: false,且不产生任何费用。previous_status— 本次调用之前翻译所处的状态,直接从记录本身读取。delete_with— 如何删除该翻译并将文件恢复为原始版本。
它不会重复翻译同一内容
与在产品中反复点击“翻译”不同,当同一文件和语言的翻译已处于 queued、translating 或 finalizing 状态时,translate_file 会拒绝重新排队;并且除非您显式传入 retry: true,否则它会拒绝重新运行失败的翻译。这是有意为之:如果重试循环每次都重新排队,那么每一轮都会消耗真实的翻译算力。
要求:付费套餐、您组织的 AI 功能已启用(默认开启;组织管理员可以在 设置 → AI 与集成 中将其关闭),以及读取和下载该文件的权限。
仍在检查中的文件。 如果该文件是 Waafir 尚未检查完毕的新上传文件或新版本,translate_file 会返回 UNAVAILABLE,附带 error.reason: "ACTIVATION_PENDING" 和消息 This file is still being checked. Try again shortly. 不会将任何任务加入队列;请稍等片刻后再次调用。
translate_file_status
检查文档翻译的状态,并在翻译就绪后获取已翻译文件的短期有效下载 URL。
输入
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_id | string | 是 | 文件的 UUID。 |
target_lang | string | 是 | 请求翻译时使用的语言。 |
输出
{ file_id, target_lang, language_name, status,
download_url?, expires_in_seconds?, download_withheld_reason? }status—not_found、queued、translating、finalizing、completed、failed或stale。stale表示在生成此翻译之后,源文件被回滚到了更早的版本,因此该翻译已与文档不再匹配,不再提供,也不会为其签发download_url。请再次调用translate_file生成新的翻译。对于任何您无法识别的状态,请视为“尚未就绪”,而不是错误。download_url— 仅当已翻译文件已就绪、可以安全地提供给您,并且令牌已开启 读取文档内容(个人访问令牌)时才会出现。它提供的副本与浏览器下载所得的副本相同,在数据室对下载添加水印的情况下会带有水印,并在几分钟后过期。每个令牌每分钟最多 10 个链接。- 未开启 读取文档内容 时,您仍然会得到
status,并且download_withheld_reason为content_grant_required。 download_withheld_reason— 当文件已就绪但被暂扣时,以此字段代替download_url出现。常见情况是:文档已经过脱敏,而您请求的翻译是基于原始文档生成的,因此提供它会泄露已被脱敏移除的内容。请重新运行translate_file,生成对脱敏安全的翻译。
此工具签发的每个下载 URL 都会作为一次文件下载记录在您组织的审计记录中,归属于该令牌并标记为来自 AI 客户端,与通过产品进行的下载的记录方式完全相同。