language-detector-api

用途

该技能面向需要在浏览器网页应用中集成 Language Detector API 的开发者，帮助在 JavaScript 或 TypeScript 项目中实现并调试语言检测功能。它适用于添加 LanguageDetector 支持检查、会话创建、文本语言检测以及相关降级处理的场景。

主要能力

技能以分步流程组织工作：

1. 识别浏览器集成面：检查工作区中的浏览器入口点、UI 处理器、文本输入流程以及已有的 AI 抽象层。在具备 Node 运行时的情况下，可执行 node scripts/find-language-detector-targets.mjs . 来盘点可能的前端文件和已有的 Language Detector API 标记。若没有 Node 运行时，则手动检查最近的 package.json、HTML 入口点和框架引导文件。若存在多个前端应用，优先选择包含活动路由、组件或用户请求功能面的应用；若仍无法确定，则停止并询问应集成到哪个应用。若项目不是浏览器网页应用，则说明该技能不适用。

2. 确认 API 可行性并选择集成形态：在编写代码前阅读 references/language-detector-reference.md；当功能需要会话封装、下载进度 UI、置信度阈值或清理形态时，阅读 references/examples.md；当涉及预览标志、浏览器渠道、iframe 规则或环境约束时，阅读 references/compatibility.md；当支持检查、创建、检测或清理失败时，阅读 references/troubleshooting.md。同时验证功能运行在安全的 Window 上下文中，并确认当前 frame 被允许使用 language-detector 的 permissions-policy 特性。根据任务选择最窄的会话形态：通用语言检测使用裸 LanguageDetector.create()；当产品依赖较窄语言集或需要针对已知语言获得更好准确度时使用 expectedInputLanguages；当 UI 需要展示模型下载进度时使用 monitor。若功能必须在 worker、服务器或仅云端契约中运行，则说明平台不匹配。若项目使用 TypeScript，则为所用 API 面添加或保留窄类型定义。

3. 实现带守卫的会话封装：阅读 assets/language-detector-session.template.ts 并适配到工作区的框架、状态模型和文件布局。围绕 globalThis.isSecureContext、LanguageDetector 以及运行时将使用的相同 expectedInputLanguages 形态集中进行支持检查。使用与将传给 LanguageDetector.create() 相同的创建选项，通过 LanguageDetector.availability() 来门控会话创建。将 availability() 视为能力检查，而非创建必然成功的保证（可能仍需下载时间、策略批准或用户激活）。当创建可能触发模型下载时，仅在用户激活后创建会话。当产品需要下载进度时，在 create() 期间使用 monitor 选项。对可取消的 create()、detect() 或 measureInputUsage() 调用使用 AbortController，并在不再需要会话时调用 destroy()。创建后不要修改 expectedInputLanguages，而应重新创建会话，因为会话选项在每个实例中是固定的。若功能位于跨源 iframe 中，需要通过 allow="language-detector" 显式委托。

4. 接入用户体验与降级行为：为缺失 API、不安全上下文、被阻止的 frame、可下载或下载中的模型、就绪会话、进行中的检测以及已中止的工作呈现不同状态。为不支持的浏览器、被阻止的 frame 或不满足当前预览要求的环境保留非 AI 降级方案。将极短文本、单个词和混合语言片段视为低置信度输入，呈现置信度感知的 UI，而不是假装最高结果总是可靠。当产品需要排序候选时保留完整有序结果列表，并在产品逻辑中应用置信度阈值或 und 处理，而不是静默截断。将末尾的 und 结果视为有意义的不确定性，而非需要移除的缺陷。当配额或输入大小预算影响流程时使用 measureInputUsage()。不要将翻译、摘要或通用聊天任务路由到此 API；当任务不是语言检测时，改用 Translator、Writing Assistance APIs、Prompt API 或其他获批能力。

5. 验证行为：执行 node scripts/find-language-detector-targets.mjs . 确认预期的应用边界和 Language Detector API 标记仍解析到已编辑的集成面。在深入调试运行时故障前，验证安全上下文检查、LanguageDetector 特性检测和 availability() 行为。至少测试一个使用代表性用户文本的 create() 加 detect() 流程。若功能依赖 expectedInputLanguages，测试受限和非受限两条路径，或确认为何只有一条有效。确认取消以预期的中止原因拒绝，且已销毁的会话不被重用。若目标环境依赖预览浏览器标志或渠道特定行为，在将失败视为应用缺陷前，从 references/compatibility.md 确认所需浏览器状态。编辑后运行工作区构建、类型检查或测试。

错误处理

• 若 LanguageDetector 缺失，保留非 AI 降级方案，并在更改产品逻辑前确认安全上下文、浏览器、渠道和标志要求。
• 若 availability() 返回 downloadable 或 downloading，需要用户驱动的会话创建，然后才能承诺检测已就绪。
• 若 create() 抛出 NotAllowedError，检查 permissions-policy 约束、下载缺少用户激活、浏览器策略限制或用户拒绝。
• 若 detect() 抛出 InvalidStateError，确认文档仍完全活动，必要时在重大生命周期变化后重新创建会话。
• 若检测调用抛出 QuotaExceededError，减小输入大小或在重试前测量用量。
• 若功能必须在 worker 或服务器上下文中运行，说明 Language Detector API 是仅限 window 的浏览器 API。

适用场景与限制

该技能适用于浏览器网页应用中的语言检测集成，尤其是需要处理支持检查、会话生命周期、下载进度、置信度与降级逻辑的场景。它不适用于非浏览器项目、worker 或服务器上下文，也不应用于翻译、摘要或通用聊天任务。具体浏览器版本、渠道、标志要求及平台支持情况需参考技能内附的兼容性文档，本介绍未提供相关细节。