translator-api

翻译器 API

流程

步骤 1：确定浏览器集成入口

1. 检查工作区中的浏览器入口、文本输入流程、本地化界面，以及现有的 AI 抽象层。
2. 如果可以使用 Node 运行时，请执行 node scripts/find-translator-targets.mjs .，盘点可能的前端文件和现有的 Translator API 标记。
3. 如果无法使用 Node 运行时，请手动检查最近的 package.json、HTML 入口文件和框架引导文件，以确定浏览器应用边界。
4. 如果工作区包含多个前端应用，请优先选择包含活动路由、翻译界面或用户请求的功能入口的应用。
5. 如果盘点后仍有多个可能的前端目标，请暂停并询问应将 Translator API 集成到哪个应用中。
6. 如果项目不是浏览器 Web 应用，请暂停并说明此技能不适用。

步骤 2：确认 API 是否可用并选择集成方式

1. 编写代码前，请阅读 references/translator-reference.md。
2. 如果功能需要会话封装、下载进度界面、流式输出、取消操作或清理方式，请阅读 references/examples.md。
3. 如果涉及预览版标志、浏览器渠道、iframe 规则或环境限制，请阅读 references/compatibility.md。
4. 如果支持性检查、会话创建、翻译或清理失败，请阅读 references/troubleshooting.md。
5. 确认功能在安全的 Window 环境中运行。
6. 确认当前框架获准使用 translator 权限策略功能。
7. 选择与任务相匹配的最精简会话形式：
   • 对于固定语言对和完整结果翻译，使用 Translator.create()。
   • 如果界面需要显示模型下载进度，使用带监控的 create()。
   • 如果界面应逐步显示译文，使用 translateStreaming()。
   • 如果流程需要考虑配额或输入长度预算，使用 measureInputUsage()。
8. 如果功能必须在 worker、服务器上运行，或通过云翻译约定运行，请暂停并说明平台不匹配。
9. 如果项目使用 TypeScript，请为功能所用的 Translator API 接口添加或保留精简的类型定义。

步骤 3：实现带保护措施的翻译器会话

1. 阅读 assets/translator-session.template.ts，并根据工作区中的框架、状态模型和文件布局进行调整。
2. 集中进行支持性检查，涵盖 globalThis.isSecureContext、Translator，以及功能运行时使用的相同 sourceLanguage 和 targetLanguage 结构。
3. 使用将传递给 Translator.create() 的同一语言对，通过 Translator.availability() 检查后再创建会话。
4. 将 availability() 视为能力检查，而非保证会话创建一定成功；创建过程仍可能需要下载时间、策略批准或用户激活。
5. 如果创建会话可能触发模型下载，请仅在用户激活后创建会话。
6. 如果产品需要显示下载进度，请在调用 create() 时使用 monitor 选项。
7. 对可取消的 create()、translate()、translateStreaming() 或 measureInputUsage() 调用使用 AbortController，并在不再需要会话时调用 destroy()。
8. 会话创建后，不要修改 sourceLanguage 或 targetLanguage；应重新创建会话。每个实例的会话选项都是固定的。
9. 如果功能位于跨域 iframe 中，请通过 allow="translator" 明确授予权限。 步骤 4：接入用户体验和回退行为
10. 明确呈现以下不同状态：缺少 API、不安全上下文、被阻止的框架、不支持的语言对、可下载或正在下载的模型、就绪的会话、正在进行的翻译，以及已中止的工作。
11. 对于不支持的浏览器、被阻止的框架或不符合当前预览要求的环境，保留非 AI 回退方案。
12. 在产品状态中明确保存源语言和目标语言对，不要根据翻译结果推断。
13. 当后续逻辑需要完整结果才能继续时，使用 translate()；当界面应逐步显示译文时，使用 translateStreaming()。
14. 当较大的输入可能超出会话配额时，使用 measureInputUsage()。
15. 将同语言翻译或最佳匹配的原样翻译视为有效结果；即使翻译结果与输入一致，也不要强制回退。
16. 对长时间运行的产品工作流进行有计划的分块或排队；翻译请求不能替代通用摘要、写作或聊天任务。
17. 不要通过此 API 执行通用云端翻译、文档本地化流程或服务器端批量翻译；如果任务不是浏览器端设备本地翻译，请改用获批的服务或运行时。

步骤 5：验证行为

1. 执行 node scripts/find-translator-targets.mjs .，确认预期的应用边界和 Translator API 标记仍能定位到已编辑的集成区域。
2. 在排查更深层的运行时故障之前，验证安全上下文检查、Translator 功能检测和 availability() 行为。
3. 使用目标语言对的典型用户文本，至少测试一条 create() 加 translate() 流程。
4. 如果该功能提供流式传输，请单独测试 translateStreaming()，并确认中止时部分输出会正常停止。
5. 如果该功能依赖配额预算，请在发送大段输入前验证 measureInputUsage() 的行为。
6. 确认取消操作会以预期的中止原因拒绝，并且已销毁的会话不会被重复使用。
7. 如果目标环境依赖预览版浏览器标志或特定渠道行为，请在将故障视为应用程序问题之前，先根据 references/compatibility.md 确认所需的浏览器状态。
8. 编辑后运行工作区构建、类型检查或测试。

错误处理

• 如果缺少 Translator，请保留非 AI 回退方案，并在更改产品逻辑前确认安全上下文、浏览器、渠道和标志要求。
• 如果 availability() 返回 downloadable 或 downloading，则必须要求用户主动创建会话，才能承诺翻译已就绪。
• 如果 create() 抛出 NotAllowedError，请检查权限策略限制、下载操作是否缺少用户激活、浏览器策略限制或用户拒绝。
• 如果 create() 抛出 OperationError，请将其视为模型初始化失败；仅在检查浏览器状态、所需标志和下载就绪状态后重试。
• 如果翻译调用抛出 QuotaExceededError，请缩小输入，或在重试前测量用量。
• 如果翻译调用抛出 NotReadableError 或 UnknownError，请显示明确的回退方案，不要盲目地使用相同输入重试。
• 如果该功能必须在 worker 或服务器上下文中运行，请停止操作并说明 Translator API 是仅限 window 使用的浏览器 API。