翻译

Web 功能： 翻译工具

借助 Translator API，开发者可以使用 Chrome 和 Edge 中的内置 AI 模型执行客户端文本翻译。这种方法无需针对临时内容使用基于云的翻译服务，从而降低了成本，并通过将数据保留在用户设备上提高了隐私保护。

前提条件和要求

API Surface 和全局范围

  • 强制性要求：只能通过全局 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)。

建议的进度监控：您应实现模型下载进度监控，方法是向 Translator.create() 提供 monitor(m) 回调，并为 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：阿拉伯语
  • bg：保加利亚语
  • bn：孟加拉语
  • cs：捷克语
  • da：丹麦语
  • de：德语
  • el：希腊语
  • en：英语
  • es：西班牙语
  • fi：芬兰语
  • fr：法语
  • hi：印地语
  • hr：克罗地亚语
  • hu：匈牙利语
  • id：印度尼西亚语
  • it：意大利语
  • he：希伯来语
  • ja：日语
  • kn：卡纳达语
  • ko：韩语
  • lt：立陶宛语
  • mr：马拉地语
  • nl：荷兰语
  • no：挪威语
  • pl：波兰语
  • pt：葡萄牙语
  • ro：罗马尼亚语
  • ru：俄语
  • sk：斯洛伐克语
  • sl：斯洛文尼亚语
  • sv：瑞典语
  • ta：泰米尔语
  • te：泰卢固语
  • th：泰语
  • tr：土耳其语
  • 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 使用费用。