Waafir
本页面为机器翻译,尚待人工审核,可能存在错误。

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

将一段短文本翻译为目标语言。该调用是同步的,输入文本、输出文本。省略源语言即可自动检测;返回结果中会包含检测到的(或您提供的)源语言,以便您确认。

输入

字段类型必填说明
textstring是要翻译的文本,1–10,000 个 UTF-8 字节。
target_langstring是目标语言代码,例如 fr、ar、es。
source_langstring否源语言代码。省略则自动检测。

输出

{ 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_idstring是文件的 UUID。
target_langstring是目标语言代码,必须是产品支持文档翻译的 28 种语言之一。
retryboolean否重新运行先前失败的翻译。对于已完成或进行中的翻译,此参数会被忽略。

输出

{ 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_idstring是文件的 UUID。
target_langstring是请求翻译时使用的语言。

输出

{ 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 客户端,与通过产品进行的下载的记录方式完全相同。