translator-api

Translator API

手順

ステップ 1：ブラウザー統合の対象範囲を特定する

1. ワークスペースを調べ、ブラウザーのエントリーポイント、テキスト入力のフロー、ローカライズ UI、既存の AI 抽象化レイヤーを確認します。
2. Node ランタイムが利用可能な場合は、node scripts/find-translator-targets.mjs . を実行して、有力なフロントエンドファイルと既存の Translator API マーカーを一覧表示します。
3. Node ランタイムが利用できない場合は、最も近い package.json、HTML エントリーポイント、フレームワークのブートストラップファイルを手動で確認し、ブラウザーアプリの境界を特定します。
4. ワークスペースに複数のフロントエンドアプリがある場合は、アクティブなルート、翻訳 UI、またはユーザーが依頼した機能の対象範囲を含むアプリを優先します。
5. 一覧を確認しても有力なフロントエンドの候補が複数残る場合は、作業を中断し、Translator API をどのアプリに統合するか尋ねます。
6. プロジェクトがブラウザー向けの Web アプリでない場合は、作業を中断し、このスキルが適用されないことを説明します。

ステップ 2：API の実現可能性を確認し、統合方法を選ぶ

1. コードを書く前に references/translator-reference.md を読みます。
2. セッションラッパー、ダウンロード進捗 UI、ストリーミング出力、キャンセル、またはクリーンアップの方法が必要な機能では、references/examples.md を読みます。
3. プレビュー用フラグ、ブラウザーチャネル、iframe のルール、または環境上の制約が関係する場合は、references/compatibility.md を読みます。
4. サポート確認、セッション作成、翻訳、またはクリーンアップに失敗した場合は、references/troubleshooting.md を読みます。
5. 機能がセキュアな Window コンテキストで実行されることを確認します。
6. 現在のフレームが translator 権限ポリシー機能を使用できることを確認します。
7. タスクに合った最小限のセッション形式を選びます。
   • 言語ペアが固定され、翻訳結果全体が必要な場合は、Translator.create() のみ
   • UI にモデルのダウンロード進捗を表示する必要がある場合は、監視付きの create()
   • UI で翻訳結果を段階的に表示する場合は、translateStreaming()
   • 割り当て量や入力サイズの見積もりがフローに影響する場合は、measureInputUsage()
8. 機能をワーカー上、サーバー上、またはクラウド翻訳の契約を通じて実行する必要がある場合は、作業を中断し、プラットフォームが適合しないことを説明します。
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：UX とフォールバック動作を組み込む
10. API が利用できない場合、安全でないコンテキスト、ブロックされたフレーム、サポートされていない言語ペア、ダウンロード可能またはダウンロード中のモデル、準備完了のセッション、進行中の翻訳、キャンセルされた処理について、それぞれ異なる状態を表示します。
11. サポート対象外のブラウザー、ブロックされたフレーム、または現在のプレビュー要件を満たさない環境では、非 AI のフォールバックを用意します。
12. 翻訳結果から推測するのではなく、ソース言語とターゲット言語のペアをプロダクトの状態に明示的に保持します。
13. 後続のロジックで続行前に結果全体が必要な場合は translate() を使用し、UI で翻訳テキストを段階的に表示する場合は translateStreaming() を使用します。
14. 大きな入力がセッションのクォータを超える可能性がある場合は、measureInputUsage() を使用します。
15. 同一言語への翻訳や最適な結果が入力と同じになる翻訳も有効な結果として扱い、翻訳結果が入力と一致した場合にフォールバックを強制しないようにします。
16. 長時間実行されるプロダクトのワークフローは、計画的に分割またはキューに入れます。翻訳リクエストは、汎用的な要約、文章作成、チャットタスクの代替ではありません。
17. 汎用的なクラウド翻訳、ドキュメントのローカライズパイプライン、サーバー側の一括翻訳をこの API 経由で実行しないでください。ブラウザー上のオンデバイス翻訳以外のタスクには、承認済みのサービスまたはランタイムに切り替えてください。

ステップ 5：動作を検証する

1. node scripts/find-translator-targets.mjs . を実行し、意図したアプリの境界と Translator API のマーカーが、編集した統合箇所を引き続き特定できることを確認します。
2. より深いランタイム障害のデバッグに進む前に、安全なコンテキストのチェック、Translator の機能検出、availability() の動作を確認します。
3. ターゲットの言語ペアに対応する代表的なユーザーテキストを使い、create() と translate() を組み合わせたフローを少なくとも 1 つテストします。
4. この機能でストリーミングを公開する場合は、translateStreaming() を個別にテストし、中断時に部分出力が適切に停止することを確認します。
5. この機能がクォータの割り当てに依存する場合は、大きな入力を送信する前に measureInputUsage() の動作を検証します。
6. キャンセル時に想定される中断理由で拒否されることと、破棄されたセッションが再利用されないことを確認します。
7. ターゲット環境がプレビューブラウザーのフラグやチャネル固有の動作に依存する場合、障害をアプリケーションのバグと見なす前に、references/compatibility.md で必要なブラウザーの状態を確認します。
8. 編集後にワークスペースのビルド、型チェック、またはテストを実行します。

エラー処理

• Translator が見つからない場合は、非 AI のフォールバックを維持し、プロダクトのロジックを変更する前に、安全なコンテキスト、ブラウザー、チャネル、フラグの要件を確認します。
• availability() が downloadable または downloading を返す場合、翻訳の準備ができていると案内する前に、ユーザー操作によるセッション作成を必須とします。
• create() が NotAllowedError をスローする場合は、Permissions Policy の制約、ダウンロードに必要なユーザーアクティベーションの不足、ブラウザーのポリシー制限、またはユーザーによる拒否を確認します。
• create() が OperationError をスローする場合は、モデルの初期化失敗として扱い、ブラウザーの状態、必要なフラグ、ダウンロードの準備状況を確認してから再試行します。
• 翻訳呼び出しが QuotaExceededError をスローする場合は、再試行する前に入力サイズを小さくするか、使用量を測定します。
• 翻訳呼び出しが NotReadableError または UnknownError をスローする場合は、同じ入力でむやみに再試行せず、ユーザーに見えるフォールバックを提示します。
• この機能をワーカーまたはサーバーのコンテキストで実行する必要がある場合は処理を中止し、Translator API はウィンドウでのみ使用できるブラウザー API であることを説明します。