譯者

網頁功能： 翻譯工具

開發人員可透過 Translator API，使用 Chrome 和 Edge 的內建 AI 模型，在用戶端翻譯文字。這種做法可避免使用雲端式翻譯服務處理臨時內容，進而降低成本，並將資料保留在使用者裝置上，提升隱私權。

必備條件和規定

API 介面和全域範圍

  • 必要：一律透過全域 Translator 介面 (window.Translator/self.Translator) 存取 Translator API。
  • 請勿使用或檢查已淘汰的 window.ai.translator 命名空間。

瀏覽器支援

  • Chrome：138 以上版本 (僅限電腦)。
  • Edge：148 以上版本 (僅限電腦)。
  • 不支援：行動裝置 (Android/iOS)、Firefox、Safari。

硬體需求

如要執行 Gemini Nano 和相關模型，系統必須符合下列條件：

  • 作業系統：Windows 10/11、macOS 13 以上版本、Linux 或 ChromeOS (Chromebook Plus)。
  • 儲存空間：設定檔磁碟區至少要有 22 GB 可用空間。
  • 記憶體/CPU：16 GB 以上 RAM 和 4 個以上 CPU 核心。
  • GPU：4 GB 以上 VRAM (Prompt API 搭配音訊時必備)。
  • 網路：只有在初次下載語言套件/模型時才需要。

導入和程式碼範例

1. 檢查可用性及管理模型

必須傳遞選項：您必須將包含 sourceLanguage 和 targetLanguage 的相同設定選項物件，傳遞至 Translator.availability(options) 和 Translator.create(options)。

建議監控進度：您應監控模型下載進度，方法是將 monitor(m) 回呼提供給 Translator.create()，並為 downloadprogress 事件新增事件監聽器，讓使用者能查看模型下載進度。

使用者手勢規定：呼叫 availability(options) 傳回 'downloadable' 或 'downloading' 時，呼叫 Translator.create() 會觸發語言套件下載，且嚴格要求使用者手勢 (例如點選按鈕)，以避免 NotAllowedError。

Translator.availability(options) 會傳回下列四種字串狀態之一：

  • 'available'：語言組合模型已下載到裝置上，可立即翻譯。
  • 'downloadable'：支援該語言組合，但需要下載模型。必須有使用者手勢才能啟動 Translator.create()。
  • 'downloading'：語言套件目前正在下載中。使用使用者手勢呼叫 Translator.create()，即可附加至下載。
  • 'unavailable'：不支援該語言組合或裝置。執行備用策略。
// Language pair options passed to both availability() and create()
const options = {
  sourceLanguage: 'es', // Example BCP 47 language code
  targetLanguage: 'fr', // Example BCP 47 language code
};

// 1. Check availability for the language pair
const availability = await Translator.availability(options);

if (availability === 'available') {
  // Model is ready immediately on device
  const translator = await Translator.create(options);
} else if (availability === 'downloadable' || availability === 'downloading') {
  // User gesture is strictly required before create() triggers or attaches to download
  document.getElementById('start-translation-btn').addEventListener('click', async () => {
    const translator = await Translator.create({
      ...options,
      monitor(m) {
        m.addEventListener('downloadprogress', (e) => {
          console.log(`Downloaded ${Math.round(e.loaded * 100)}%`);
        });
      },
    });
  });
} else if (availability === 'unavailable') {
  // Language pair or hardware unsupported; execute fallback
  console.warn('Translation model is unavailable on this device.');
}

2. 執行翻譯

API 支援靜態和串流回應。例項化翻譯工具時，請務必加入下載進度監控功能。

標準翻譯：

// Default to including a progress monitor when creating translator
const translator = await Translator.create({
  sourceLanguage: 'en',
  targetLanguage: 'fr',
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${Math.round(e.loaded * 100)}%`);
    });
  },
});

const result = await translator.translate(
  'Where is the next bus stop, please?',
);
console.log(result);
// Output: "Où est le prochain arrêt de bus, s'il vous plaît ?"

串流翻譯 (適用於長篇文字)：

const stream = translator.translateStreaming(longText);
for await (const chunk of stream) {
  console.log(chunk);
}

支援的語言

這個 API 支援多種 BCP 47 語言代碼。以下是 Chrome 實作 Translator API 支援的語言：

  • ar: Arabic
  • bg: Bulgarian
  • bn：孟加拉文
  • cs：捷克文
  • da：丹麥文
  • de：德文
  • el: Greek
  • en：英文
  • es: Spanish
  • fi: Finnish
  • fr: French
  • hi: Hindi
  • hr：克羅埃西亞文
  • hu: Hungarian
  • id: Indonesian
  • it: Italian
  • he: Hebrew
  • ja: Japanese
  • kn：卡納達文
  • ko: Korean
  • lt: Lithuanian
  • mr: Marathi
  • nl: Dutch
  • no：挪威文
  • pl: Polish
  • pt: Portuguese
  • ro: Romanian
  • ru: Russian
  • sk: Slovak
  • sl: Slovenian
  • sv：瑞典文
  • ta: Tamil
  • te: 泰盧固文
  • th: Thai
  • tr: Turkish
  • uk：烏克蘭文
  • vi：越南文
  • zh：中文
  • zh-Hant：繁體中文

安全性與效能

  • 權限政策：跨來源 iframe 必須明確取得權限。

    <iframe src="https://example.com/" allow="translator"></iframe>

  • Web Worker：由於權限政策複雜，目前不支援。

  • 隱私權：下載模型後，翻譯過程中不會將任何資料傳送至 Google 伺服器。

備用策略

使用前，請檢查 Translator 物件是否可在全域範圍內使用：

if ('Translator' in self) {
  // The Translator API is supported.
} else {
  // Execute fallback strategy (do not fall back to window.ai.translator).
}

如果系統不支援 Translator API，或可用性檢查傳回 'unavailable'，您必須妥善處理。

建議選項：

  1. 遠端 API 備用方案：將翻譯要求重新導向至伺服器端點或雲端遠端 API (例如 Vertex AI Gemini API)，提供翻譯功能。
  2. 優雅降級：以視覺方式停用翻譯控制項元素或按鈕，同時顯示使用者容易理解的附註 (例如 "Client-side translation is currently unsupported in this browser")。請勿允許未處理的例外狀況。
  3. Polyfill 備用方案：您可以使用社群維護的 Polyfill (例如 built-in-ai-task-apis-polyfills 或 prompt-api-polyfill)，透過遠端服務模擬 API 介面。

隱私權和成本影響：這些 polyfill 可能會將要求代理至遠端伺服器 (例如透過雲端傳送至 Gemini API)，但也可以選擇在本機處理。遠端處理會完全破壞原生內建 AI API 的裝置端隱私權保證，而且通常會產生伺服器端 API 使用費用。