language-detector-api

语言检测器 API

流程

步骤 1：确定浏览器集成边界

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

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

1. 编写代码前，阅读 references/language-detector-reference.md。
2. 如果功能需要会话封装、下载进度 UI、置信度阈值或清理方式，请阅读 references/examples.md。
3. 如果预览标志、浏览器渠道、iframe 规则或环境限制有影响，请阅读 references/compatibility.md。
4. 如果支持检查、创建、检测或清理失败，请阅读 references/troubleshooting.md。
5. 确认功能在安全的 Window 上下文中运行。
6. 确认当前框架获准使用 language-detector 权限策略功能。
7. 选择与任务匹配的最精简会话形式：
   • 常规语言检测使用裸调用 LanguageDetector.create()
   • 当产品依赖较小的语言集或需要提高已知语言的准确性时，使用 expectedInputLanguages
   • 当 UI 必须显示模型下载进度时，使用 monitor
8. 如果功能必须在 worker、服务器上运行，或依赖纯云端契约，请停止并说明平台不匹配。
9. 如果项目使用 TypeScript，请为功能所用的 Language Detector API 表面添加或保留精简的类型定义。

步骤 3：实现带保护措施的会话封装

1. 阅读 assets/language-detector-session.template.ts，并根据工作区中的框架、状态模型和文件布局进行调整。
2. 围绕 globalThis.isSecureContext、LanguageDetector 以及功能在运行时将使用的相同 expectedInputLanguages 形式，集中进行支持情况检查。
3. 使用与传给 LanguageDetector.create() 相同的创建选项，通过 LanguageDetector.availability() 控制会话创建。
4. 将 availability() 视为功能支持检查，而不是保证创建成功且无需下载、策略许可或用户激活。
5. 如果创建可能触发模型下载，请仅在用户激活后创建会话。
6. 如果产品需要显示下载进度，请在调用 create() 时使用 monitor 选项。
7. 对可取消的 create()、detect() 或 measureInputUsage() 调用使用 AbortController，并在不再需要会话时调用 destroy()。
8. 创建后不要修改 expectedInputLanguages；应重新创建会话，因为每个实例的会话选项都是固定的。
9. 如果功能位于跨源 iframe 中，必须通过 allow="language-detector" 显式授权。 步骤 4：接入 UX 和回退行为
10. 为缺少 API、不安全上下文、被阻止的框架、可下载或正在下载的模型、就绪会话、检测进行中以及已中止的工作展示不同状态。
11. 对于不受支持的浏览器、被阻止的框架或不满足当前预览要求的环境，保留非 AI 回退方案。
12. 将极短文本、单个词语和混合语言片段视为低置信度输入；展示能够反映置信度的 UI，不要假定排名第一的结果总是可靠的。
13. 如果产品需要排名候选项，请保留完整的有序结果列表，并在产品逻辑中应用任何置信度阈值或 und 处理方式，不要静默截断结果。
14. 将末尾的 und 结果视为有意义的不确定性，而非需要移除的缺陷。
15. 当配额或输入大小预算会影响流程时，使用 measureInputUsage()。
16. 不要通过此 API 处理翻译、摘要或通用聊天任务；如果任务并非语言检测，请改用 Translator、Writing Assistance APIs、Prompt API 或其他经批准的能力。

步骤 5：验证行为

1. 执行 node scripts/find-language-detector-targets.mjs .，确认预期的应用边界和 Language Detector API 标记仍指向经过编辑的集成界面。
2. 在排查更深层的运行时故障之前，先验证安全上下文检查、LanguageDetector 特性检测和 availability() 行为。
3. 使用有代表性的用户文本，至少测试一次 create() 加 detect() 流程。
4. 如果该功能依赖 expectedInputLanguages，请测试受限和不受限两种路径，或确认为什么只有一种路径有效。
5. 确认取消操作会以预期的中止原因拒绝，并且已销毁的会话不会被重复使用。
6. 如果目标环境依赖预览版浏览器标志或特定渠道的行为，请先根据 references/compatibility.md 确认所需的浏览器状态，再将故障判定为应用 bug。
7. 编辑后运行工作区构建、类型检查或测试。

错误处理

• 如果缺少 LanguageDetector，请保留非 AI 回退方案，并在更改产品逻辑前确认安全上下文、浏览器、渠道和标志要求。
• 如果 availability() 返回 downloadable 或 downloading，则在承诺检测功能已就绪之前，要求用户主动创建会话。
• 如果 create() 抛出 NotAllowedError，请检查权限策略限制、下载缺少用户激活、浏览器策略限制或用户拒绝等情况。
• 如果 detect() 抛出 InvalidStateError，请确认文档仍处于完全活动状态；如有需要，在发生重大生命周期变化后重新创建会话。
• 如果检测调用抛出 QuotaExceededError，请缩小输入，或先测量用量再重试。
• 如果该功能必须在 worker 或服务器上下文中运行，请停止并说明 Language Detector API 是仅限 window 的浏览器 API。