用途
Translator API 技能面向在 JavaScript 或 TypeScript 浏览器 Web 应用中集成浏览器 Translator API 的开发场景，用于实现和调试相关集成。它适用于添加 Translator 支持检测、语言对处理、会话创建、翻译调用、流式输出、取消与清理等前端功能。该技能明确限定于浏览器窗口内的设备端翻译；如果功能必须运行在 Worker、服务端或通过云端翻译契约完成，则属于平台不匹配，不适用本技能。
主要能力
技能提供了一套分步骤的流程，覆盖从识别集成面到验证行为的完整链路：
-
识别浏览器集成面：检查工作区中的浏览器入口点、文本输入流程、本地化 UI 以及已有的 AI 抽象层。可执行
node scripts/find-translator-targets.mjs .来盘点可能的前端文件和已有的 Translator API 标记；若无 Node 运行时，则手动检查最近的 package.json、HTML 入口点和框架引导文件。若存在多个前端应用，优先选择包含活动路由、翻译 UI 或用户请求功能面的应用；若仍无法确定，应停止并询问应由哪个应用接收集成；若项目不是浏览器 Web 应用，应停止并说明该技能不适用。 -
确认 API 可行性并选择集成形态：在编写代码前阅读
references/translator-reference.md；当功能需要会话包装、下载进度 UI、流式输出、取消或清理形态时阅读references/examples.md；当涉及预览标志、浏览器渠道、iframe 规则或环境约束时阅读references/compatibility.md；当支持检测、会话创建、翻译或清理失败时阅读references/troubleshooting.md。需验证功能运行在安全的 Window 上下文中，并验证当前框架被允许使用 translator permissions-policy 特性。根据任务选择最窄的会话形态：固定语言对且返回完整结果时使用裸Translator.create()；UI 需要展示模型下载进度时使用带监控的create()；UI 需要增量展示翻译输出时使用translateStreaming()；配额或输入大小预算影响流程时使用measureInputUsage()。若项目使用 TypeScript，应为功能所用的 Translator API 表面添加或保留窄类型定义。 -
实现带守卫的翻译会话：阅读
assets/translator-session.template.ts并适配到工作区的框架、状态模型和文件布局。围绕globalThis.isSecureContext、Translator以及功能在运行时将使用的相同 sourceLanguage 和 targetLanguage 形态集中进行支持检测。使用与将传给Translator.create()相同的语言对，通过Translator.availability()来门控会话创建。将availability()视为能力检查，而非创建必然成功的保证——它不保证无需下载时间、策略批准或用户激活。当创建可能触发模型下载时，仅在用户激活后创建会话。产品需要下载进度时，在create()期间使用 monitor 选项。对可取消的create()、translate()、translateStreaming()或measureInputUsage()调用使用 AbortController，并在会话不再需要时调用destroy()。创建后应重新创建会话，而不是修改 sourceLanguage 或 targetLanguage；会话选项在每个实例中是固定的。若功能位于跨源 iframe 中，需要通过allow="translator"显式委托。 -
连接 UX 与降级行为：为缺失 API、不安全上下文、被阻止的框架、不支持的语言对、模型可下载或下载中、会话就绪、翻译进行中以及已中止的工作等状态提供不同的界面呈现。为不支持的浏览器、被阻止的框架或不符合当前预览要求的环境保留非 AI 降级方案。在产品状态中显式保留源语言和目标语言对，而不是从翻译输出中推断。当下游逻辑需要完整结果才能继续时使用
translate()；当 UI 应增量展示翻译文本时使用translateStreaming()；当大输入可能超出会话配额时使用measureInputUsage()。将同语言或最佳匹配的同一性翻译视为有效结果，而不是在翻译结果与输入相同时强制降级。对长时间运行的产品工作流进行有意的分块或排队；翻译请求不能替代通用摘要、写作或聊天任务。不要将通用云端翻译、文档本地化流水线或服务端批量翻译路由到此 API；当任务不是浏览器设备端翻译时，应切换到已批准的服务或运行时。 -
验证行为：执行
node scripts/find-translator-targets.mjs .确认预期的应用边界和 Translator API 标记仍解析到已编辑的集成面。在调试更深层的运行时故障之前，先验证安全上下文检查、Translator 特性检测和availability()行为。至少测试一个针对目标语言对的create()加translate()流程，使用有代表性的用户文本。若功能暴露流式输出，单独测试translateStreaming()并确认部分输出在中止时干净停止。若功能依赖配额预算，在发送大输入前验证measureInputUsage()行为。确认取消以预期的中止原因拒绝，且已销毁的会话不会被重用。若目标环境依赖预览浏览器标志或特定渠道行为，在将失败视为应用缺陷之前，从references/compatibility.md确认所需的浏览器状态。编辑后运行工作区构建、类型检查或测试。
使用方式
该技能以流程化步骤和参考文件的形式提供指导。使用时按步骤执行：先识别浏览器集成面，再确认 API 可行性并选择集成形态，然后实现带守卫的翻译会话，接着连接 UX 与降级行为，最后验证行为。过程中按需阅读 references/translator-reference.md、references/examples.md、references/compatibility.md、references/troubleshooting.md，并基于 assets/translator-session.template.ts 模板进行适配。可执行 node scripts/find-translator-targets.mjs . 辅助盘点前端目标。
适用场景
适用于在浏览器 Web 应用中添加或调试 Translator API 集成，包括支持检测、语言对处理、会话创建与销毁、下载进度展示、流式翻译输出、取消操作、配额预算以及相关 UX 状态与降级方案。
限制
该技能仅适用于浏览器窗口内的设备端翻译。若功能必须运行在 Worker 或服务端上下文，应停止并说明 Translator API 是仅限窗口的浏览器 API。不要将通用云端翻译、文档本地化流水线或服务端批量翻译路由到此 API。翻译请求不能替代通用摘要、写作或聊天任务。会话选项在每个实例中固定，创建后不能修改 sourceLanguage 或 targetLanguage，只能重新创建会话。availability() 是能力检查，不保证创建必然成功。跨源 iframe 需要显式委托。部分环境可能依赖预览浏览器标志或特定渠道行为。