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. プロジェクトがブラウザー上で動作するウェブアプリでない場合は、作業を中断し、このスキルが適用されないことを説明します。

ステップ 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 permissions-policy 機能の使用が許可されていることを確認します。
7. タスクに適合する最小限のセッション構成を選びます。
   • 一般的な言語検出には、LanguageDetector.create() のみを使用します。
   • 製品が対象言語を絞る必要がある場合、または既知の言語の精度向上を必要とする場合は、expectedInputLanguages を使用します。
   • UI にモデルのダウンロード進捗を表示する必要がある場合は、monitor を使用します。
8. この機能をワーカー、サーバー、またはクラウドのみで動作する仕様を通じて実行する必要がある場合は、作業を中断し、プラットフォームが適合しないことを説明します。
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. ごく短いテキスト、単語 1 つだけのテキスト、複数言語が混在するテキストは信頼度が低い入力として扱います。最上位の結果が常に信頼できるかのように見せるのではなく、信頼度を考慮した 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. 代表的なユーザーテキストを使って、少なくとも 1 つの create() と detect() のフローをテストします。
4. 機能が expectedInputLanguages に依存する場合は、制約ありと制約なしの両方の経路をテストするか、片方だけが有効な理由を確認します。
5. キャンセル時に想定される中断理由で拒否されることと、破棄されたセッションが再利用されないことを確認します。
6. 対象環境がプレビュー版ブラウザーのフラグやチャネル固有の動作に依存する場合は、失敗をアプリケーションの不具合とみなす前に、references/compatibility.md で必要なブラウザーの状態を確認します。
7. 編集後に、ワークスペースのビルド、型チェック、またはテストを実行します。

エラー処理

• LanguageDetector が利用できない場合は、非 AI のフォールバックを維持し、プロダクトのロジックを変更する前に、安全なコンテキスト、ブラウザー、チャネル、フラグの要件を確認します。
• availability() が downloadable または downloading を返す場合、検出の準備ができていると案内する前に、ユーザー操作によるセッション作成を必須にします。
• create() が NotAllowedError をスローする場合は、Permissions Policy の制約、ダウンロードに必要なユーザー操作の欠如、ブラウザーのポリシー制限、またはユーザーによる拒否を確認します。
• detect() が InvalidStateError をスローする場合は、ドキュメントが引き続き完全にアクティブであることを確認します。必要に応じて、ライフサイクルに大きな変化があった後にセッションを再作成します。
• 検出の呼び出しが QuotaExceededError をスローする場合は、入力サイズを小さくするか、再試行する前に使用量を測定します。
• この機能をワーカーまたはサーバーのコンテキストで実行する必要がある場合は、作業を中止し、Language Detector API はウィンドウ専用のブラウザー API であることを説明します。