← 文章 / 编程开发
freeCodeCamp 4天前 · 2026-11-18 08:14:42 · 14 阅读

如何用 Chrome 内置 AI 打造本地翻译器

大多数翻译功能的套路都一样:用户输入文字,应用把文字发给翻译 API,API 再返回译文。这样做没问题,但每次请求都有成本和延迟,而且用户的文字还会离开他们的设备。

Chrome 现在内置了两个 AI API,可以改变这一切:Translator API 和 Language Detector API。Chrome 会按需下载小型专用模型,直接在用户设备上运行。你不需要部署模型、搭建推理服务器,也不必按请求付费,只要调用 JavaScript API 就行。

本教程将带你在 Next.js 中构建一个翻译器,它能:

  • 自动检测用户输入的文字语言。
  • 翻译成用户选择的目标语言。
  • 在 Chrome 生成译文的同时流式显示到页面上。
  • 展示语言包的下载进度,并支持用户取消下载。
  • 复制译文、朗读译文、互换两种语言。
  • 妥善处理不支持这些 API 的浏览器。

目录

  1. 前置要求
  2. 国际化 vs AI 翻译
  3. Chrome 内置 AI API 的工作原理
  4. 先在 Playground 里试用这些 API
  5. 如何搭建 Next.js 项目
  6. 如何定义语言列表
  7. 如何封装 Chrome API
  8. 如何编写翻译 Hook
  9. 如何构建界面
  10. 如何运行和测试应用
  11. 局限性与生产环境注意事项
  12. 总结

前置要求

你需要熟悉:

  • JavaScript 或 TypeScript
  • React 基础(组件、props、useState、useEffect)
  • 在终端中执行命令

你还需要:

  • Node.js 20.9 或更高版本。
  • 桌面版 Chrome 138 或更高版本。 Translator 和 Language Detector API 仅在桌面版 Chrome 中可用,不支持移动设备,且 Firefox 和 Safari 也不支持。Chrome 的浏览器支持列表中还包含 Edge(148)。本教程在 macOS 上的 Chrome 156 中进行了测试。

你无需了解任何机器学习知识。

国际化与 AI 翻译

在编写代码之前,请先区分两个容易混淆的概念。

国际化(i18n)旨在让你的界面适配多种语言和地区:包括语言选择、支持地区设置的日期、数字和货币、从右到左(RTL)布局,以及由人工编写和审核的静态界面字符串:

const messages = {
  en: { welcome: "Welcome", description: "Explore our platform" },
  fr: { welcome: "Bienvenue", description: "Explorez notre plateforme" },
  es: { welcome: "Bienvenido", description: "Explora nuestra plataforma" },
};

AI 驱动翻译则实时生成译文,处理那些并非预先写好的内容,例如评论、评测、支持消息和帖子。

传统 i18n AI 驱动翻译
使用预定义的译文 动态生成译文
适用于界面文本 适用于用户生成内容
通常由开发者管理 可处理任意文本
输出结果可预测 输出结果可能有所差异

AI 翻译是对 i18n 的补充,而非替代。你仍然需要为按钮和菜单准备精心整理的字符串。Translator API 负责填补其他所有内容的缺口。

Chrome 的文档提供了一个很好的例子:在客服聊天中,用户使用母语输入消息,你的网站会在消息离开用户设备之前将其翻译成客服人员的语言。

Chrome 内置 AI API 的工作原理

有两个 API,它们协同工作:

  • LanguageDetector 接收文本并返回一个按置信度(0 到 1 之间)排序的语言列表。
  • Translator 针对特定的语言对创建(例如英文到西班牙文),并在它们之间进行翻译。

它和调用云 API、或用 Transformers.js 这类库自己跑模型有以下区别:

  1. 模型由浏览器管理。你不需要打包或托管模型文件,Chrome 会在网站首次需要时自动下载。
  2. 翻译使用语言包。Chrome 文档把语言包形容为"某种语言的词典",按需下载。首次翻译某个语言对时会触发下载,之后直接复用。
  3. 一切皆异步,且受权限控制。先调用 availability() 检查,再调用 create(),还可以监听下载进度。

根据 Chrome 文档,有四个约束条件需要在设计时考虑:

  • 需要用户激活。当需要下载模型时,创建翻译器或检测器必须由用户操作触发,比如点击。
  • 不能在 Web Workers 中使用。这两个 API 都不能在 worker 中调用,只能在主线程调用。(调用本身是异步的,模型运行在 JS 线程之外,所以不会阻塞 UI。)
  • 串行处理。翻译请求是逐个处理的,一个大请求会阻塞后续请求,因此要分块处理并显示加载提示。
  • 仅限顶层窗口。默认情况下,这些 API 只能在顶层窗口和同源 iframe 中使用。跨域 iframe 需要通过 Permissions Policy 的 allow 属性授权。

两个 API 的 availability() 方法都会返回以下四种值之一,你的 UI 应该分别处理:

取值 含义
unavailable 浏览器不支持这些选项。
downloadable 支持,但需要先下载模型。
downloading 支持,且正在下载中。
available 支持且已就绪,无需下载。

一个隐私细节:为了保护用户隐私,Chrome 会隐藏具体语言对的下载状态。在你的网站为某个语言对创建翻译器之前,所有语言对都会被报告为 downloadable。

先在 Playground 里试用这些 API

在动手写代码之前,建议先进行实验。内置 AI 游乐场提供了 Chrome 以 JavaScript API 形式暴露的 AI 功能,包括下面这两种功能。请在桌面版 Chrome 中打开并尝试:
  1. 在语言检测器中粘贴几段不同语言的句子,并查看置信度得分。
  2. 先试单个单词,再试完整句子。Chrome 的文档警告称,短输入会导致结果准确性较低,因此请对比置信度数值。
  3. 在几组语言对之间进行翻译。对于某语言对的首次翻译,Chrome 可能会暂停以下载语言包。

你将在应用中实现完全相同的行为。

如何配置 Next.js 项目

使用 TypeScript 和 App Router 创建一个 Next.js 应用。剩余提示请按需填写:

npx create-next-app@latest chrome-ai-translator --ts --app --no-tailwind --no-src-dir --import-alias "@/*"
cd chrome-ai-translator

然后安装 Chrome 内置 AI API 的 TypeScript 类型定义。TypeScript 尚不知道 Translator 或 LanguageDetector,因为它们未包含在标准 DOM 类型中:

npm install -D @types/dom-chromium-ai

该包全局声明了 Translator、LanguageDetector 及相关类型,因此你无需导入任何内容。你的编辑器现在可以自动补全 Translator.create() 并标记错误。

删除 app/page.module.css 和 public/ 目录下未使用的图片。你将替换 app/page.tsx、app/layout.tsx 和 app/globals.css。在 app/ 旁创建以下文件夹:

chrome-ai-translator/
├── app/
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── language-select.tsx
│   ├── text-panel.tsx
│   ├── translator-app.tsx
│   └── unsupported-notice.tsx
├── hooks/
│   └── use-translation.ts
└── lib/
    ├── chrome-ai.ts
    └── languages.ts

每个文件夹各司其职:

  • lib/ 包含与 Chrome API 交互的纯 TypeScript 代码。
  • hooks/ 将其转换为 React 状态。
  • components/ 包含 UI 组件。
  • app/ 包含 Next.js 页面和布局。

如何定义语言

创建 lib/languages.ts。这个文件列出 Chrome Translator API 支持的语言(来自 Chrome 官方文档)。Translator API 使用 BCP 47 代码,比如 es 或 zh-Hant:

/** Sentinel value for "detect the source language for me". */
export const AUTO = "auto";

export interface Language {
  /** BCP 47 code, as expected by the Translator API. */
  code: string;
  name: string;
  rtl?: boolean;
}

export const LANGUAGES: Language[] = [
  { code: "ar", name: "Arabic", rtl: true },
  { code: "de", name: "German" },
  { code: "en", name: "English" },
  { code: "es", name: "Spanish" },
  { code: "fr", name: "French" },
  { code: "he", name: "Hebrew", rtl: true },
  // ...the full list of 39 languages is in the repository
  { code: "zh", name: "Chinese (Simplified)" },
  { code: "zh-Hant", name: "Chinese (Traditional)" },
];

export function languageName(code: string): string {
  return LANGUAGES.find((language) => language.code === code)?.name ?? code;
}

export function isRtl(code: string): boolean {
  return LANGUAGES.find((language) => language.code === code)?.rtl ?? false;
}

硬编码这份列表在教程里没问题,但 Chrome 明确表示这是它自己实现特有的,可能会有变动,而且目前还没有动态获取列表的函数。所以应用每次翻译前仍需调用 Translator.availability()。这份列表只决定下拉框里显示哪些选项。

rtl 标记用于让阿拉伯语和希伯来语的输出从右向左渲染。

如何封装 Chrome API

接下来创建 lib/chrome-ai.ts。这个文件是项目的核心,所有对 Chrome Translator 和 Language Detector API 的调用都集中在这里,应用的其他部分不会直接接触这些 API。

我们会一段一段地构建这个文件,每段代码依次添加在上一段之后。这个文件里的所有代码都只在浏览器中运行,所以要从 Client Components 中导入。

第 1 步:添加共享常量、类型和错误类

先在文件开头写几个小定义,后面的函数都会用到它们:

/**
 * 围绕 Chrome 内置 Translator 和 Language Detector API 的轻量辅助工具。
 * 这里的所有代码仅在浏览器中运行。请从 Client Components 中引入。
 */

/** 当检测置信度低于此阈值时,我们让用户手动选择语言,而不是直接猜测。 */
export const CONFIDENCE_THRESHOLD = 0.6;

export type DownloadProgress = (fraction: number) => void;

export class LowConfidenceError extends Error {
  constructor() {
    super("无法识别该文本的语言。请手动选择源语言。");
  }
}

export class UnsupportedPairError extends Error {
  constructor(source: string, target: string) {
    super(`当前设备不支持从 "${source}" 翻译到 "${target}"。`);
  }
}

以下是各部分的作用说明:

  • CONFIDENCE_THRESHOLD 是语言检测器可接受的最小置信度分数。语言检测是概率性判断,而非绝对事实。Chrome 官方文档警告称,极短的短语和单个词会导致低准确率结果,建议将置信度过低的结果视为未知。稍后编写的 Hook 会将每个检测结果与此数值进行比较。0.6 是一个起始值,你可以根据实际用户情况进行调整。
  • DownloadProgress 是接收下载进度回调的类型。Chrome 报告的进度是一个从 0 到 1 的比例,因此 0.5 表示语言包已下载一半。
  • LowConfidenceError 在检测器无法判断文本语言时抛出。为其定义独立的类,可以让 Hook 将其与其他错误区分开来,其错误信息也会告知用户下一步该如何操作。
  • UnsupportedPairError 在 Chrome 报告无法在两种语言间进行翻译时抛出。它包含了两种语言的代码,以便用户了解哪对语言翻译失败。

步骤 2:检查浏览器是否支持相关 API

添加功能检测函数:

/** 功能检测。在服务器上始终为 false,因为不存在 `self.Translator`。 */
export function isBuiltInAISupported(): boolean {
  return typeof self !== "undefined" && "Translator" in self && "LanguageDetector" in self;
}

Next.js 首先会在服务器上渲染组件,而服务器环境中没有 self.Translator。此函数检查以下三点:

  • typeof self !== "undefined" 确保当前上下文中 self 确实存在,这样函数在服务器端不会崩溃。
  • "Translator" in self 是 Chrome 官方文档推荐的 Translator API 检测方式。
  • "LanguageDetector" in self 是针对 Language Detector API 的对应检测。这个应用两个 API 都要用到,所以只有两者都存在时才报告支持。

该函数只返回 true 或 false,不会抛出异常。稍后你会用它来决定显示翻译器还是“不支持”的提示。

第 3 步:创建语言检测器

接下来,添加创建检测器的代码。这里你将首次看到 monitor 回调和下载进度:

let detectorPromise: Promise<LanguageDetector> | null = null;

function getDetector(onProgress?: DownloadProgress) {
  detectorPromise ??= LanguageDetector.create({
    monitor(monitor) {
      monitor.addEventListener("downloadprogress", (event) => onProgress?.(event.loaded));
    },
  });
  // 如果创建失败(例如缺少用户激活),下次点击时允许重试。
  detectorPromise.catch(() => {
    detectorPromise = null;
  });
  return detectorPromise;
}

getDetector() 的工作原理如下:

  • detectorPromise 是一个模块级变量,用来保存检测器。我们存的是 promise,而不是已创建好的检测器。这样即使应用中两个地方同时请求检测器,也只会共享一次创建过程,而不是各自启动一次。
  • ??= 表示“仅在变量为 null 或 undefined 时才赋值”。第一次调用会执行 LanguageDetector.create(),之后的调用都会复用已存储的 promise。
  • monitor 选项是一个回调,Chrome 会传入一个 CreateMonitor 对象。我们监听它的 downloadprogress 事件,把 event.loaded(0 到 1 之间的进度值)传给 onProgress。Chrome 的检测模型很小,可能已经预装在设备上,所以这个事件可能永远不触发。我们仍然要处理它,因为首次下载时可能会触发。
  • 如果创建失败,.catch() 会将 detectorPromise 重置为 null。若缺少此逻辑,一旦创建尝试失败(例如 Chrome 需要用户点击但未获得响应),该失败状态将永远被缓存,导致用户无法重试。

第 4 步:检测文本语言

接下来添加使用该检测器的函数:

export interface Detection {
  language: string;
  confidence: number;
}

export async function detectLanguage(
  text: string,
  onProgress?: DownloadProgress,
  signal?: AbortSignal,
): Promise<Detection | null> {
  const detector = await getDetector(onProgress);
  // Results are ranked from most to least likely. The last entry is always "und" (undetermined).
  const [top] = await detector.detect(text, { signal });
  if (!top?.detectedLanguage || top.detectedLanguage === "und") return null;
  return { language: top.detectedLanguage, confidence: top.confidence ?? 0 };
}

以下是代码的功能说明:

  • Detection 接口定义了返回值内容:一个 BCP 47 语言代码(如 "es")和一个介于 0 到 1 之间的置信度分数。
  • detectLanguage() 首先等待 getDetector() 返回检测器。它传递 onProgress 参数,以便 UI 能够显示下载进度条。
  • detector.detect(text, { signal }) 返回一个按可能性从高到低排序的猜测列表,每项包含 detectedLanguage 和 confidence。这里的 signal 是一个 AbortSignal,允许用户取消正在进行的检测。
  • 数组解构 [top] 仅提取最佳猜测结果。
  • Chrome 返回结果中的最后一项始终是 und,意为“未确定”。这代表文本不属于模型已知语言的概率。如果最佳猜测缺失或为 und,函数返回 null,表示“无答案”。
  • 否则,函数返回语言代码和置信度。使用 ?? 0 作为兜底措施,因为 TypeScript 将 confidence 定义为可选类型。

第 5 步:创建并缓存翻译器

语言对逻辑位于翻译环节。接下来添加以下内容:

// 一个 Translator 只对应一个语言对。创建开销很大,所以我们把它缓存起来。
const translators = new Map<string, Translator>();

export async function getTranslator(
  sourceLanguage: string,
  targetLanguage: string,
  onProgress?: DownloadProgress,
  signal?: AbortSignal,
): Promise<Translator> {
  const key = `${sourceLanguage}>${targetLanguage}`;
  const cached = translators.get(key);
  if (cached) return cached;

  const availability = await Translator.availability({ sourceLanguage, targetLanguage });
  if (availability === "unavailable") {
    throw new UnsupportedPairError(sourceLanguage, targetLanguage);
  }

  const translator = await Translator.create({
    sourceLanguage,
    targetLanguage,
    signal,
    monitor(monitor) {
      monitor.addEventListener("downloadprogress", (event) => onProgress?.(event.loaded));
    },
  });
  translators.set(key, translator);
  return translator;
}

这个函数按照 Chrome 文档描述的生命周期,分四步工作:

  1. 查缓存。一个 Translator 只能对应一个语言对,而创建它的开销很大,所以我们用一个 Map 缓存,以 "en>es" 这类字符串作为键。如果这个语言对的翻译器已经存在,就直接返回。这也是翻译第二句话时速度快的原因。
  2. 检查可用性。Translator.availability() 告诉我们 Chrome 能否处理这个语言对,返回值可能是 unavailable、downloadable、downloading 或 available。如果是 unavailable,我们会先抛出 UnsupportedPairError,避免为永远无法工作的语言对启动下载。
  3. 创建翻译器。Translator.create() 接收语言对、用于取消的 signal,以及一个 monitor——它上报下载进度的方式和前面检测器完全一样。如果需要下载语言包,Chrome 会在这里自动开始下载。当需要下载时,这一步还要求有用户手势(比如点击)触发。
  4. 保存并返回。把新建的翻译器存入 Map 以备下次使用,然后返回它。

第 6 步:用完后释放模型

添加一个释放内存的函数:

/** 释放模型占用的内存。当用户离开该功能时调用。 */
export async function destroyAll() {
  for (const translator of translators.values()) translator.destroy();
  translators.clear();
  const pending = detectorPromise;
  detectorPromise = null;
  (await pending?.catch(() => null))?.destroy();
}

MDN 建议在完成 Translator 或 LanguageDetector 的使用后调用 destroy(),因为它们会消耗大量资源。这个函数会处理我们创建的所有对象:

  • for 循环为每个缓存的翻译器调用 destroy(),随后 translators.clear() 清空缓存,确保后续请求会创建一个全新的实例。
  • 检测器的处理稍微复杂些,因为这里存储的是 Promise 而非检测器对象本身。我们将 Promise 复制到 pending 中,将共享变量重置为 null,然后等待该 Promise 完成。
  • pending?.catch(() => null) 用于处理两种边界情况:可能根本没有检测器,或者创建过程失败。在这两种情况下都会得到 null,最后的 ?.destroy() 将不执行任何操作。

接下来你要编写的 Hook 会在组件卸载时调用 destroyAll()。

第 7 步:将 API 错误转化为有用的提示信息

最后,添加一个函数,向用户解释失败原因:

/** 将这些 API 抛出的 DOMException 转化为可操作的提示信息。 */
export function describeError(error: unknown): string {
  if (error instanceof DOMException) {
    switch (error.name) {
      case "NotAllowedError":
        return "Chrome 需要一次新的点击才能开始下载。请再次点击翻译。";
      case "NotSupportedError":
        // 在全新的 Chrome 配置文件中,系统仍在获取组件时也会抛出此错误。
        return "Chrome 无法准备该翻译。如果是首次使用,请等待片刻后重试;否则,可能是设备不支持该语言。";
      case "QuotaExceededError":
        return "文本过长。请尝试翻译较短的段落。";
      case "NetworkError":
        return "无法下载语言包。请检查网络连接并重试。";
    }
  }
  return error instanceof Error ? error.message : "出了点问题。";
}

内置 AI API 通过抛出 DOMException 来报告问题,异常的 name 属性说明了具体哪里出了问题。这个函数把每个名称映射成一条用户能看懂并采取行动的消息:

  • NotAllowedError:Chrome 需要用户手势(比如点击)才能开始下载组件,但没有检测到。提示用户再按一次 Translate 即可解决。
  • NotSupportedError:MDN 文档说这是请求的语言不受支持时抛出的错误。但我在测试中还发现,全新的 Chrome 配置文件在第一次调用时也会抛出这个错误——因为 Chrome 还在准备组件,再试一次就好了。这条消息覆盖了这两种情况。
  • QuotaExceededError:MDN 文档说这是输入超出可用配额时抛出的错误,也就是说文本太长了。
  • NetworkError:语言包下载失败。

对于其他情况,如果抛出的是普通 Error,函数就直接返回其自带的错误信息,否则返回一条通用提示。

至此,lib/chrome-ai.ts 文件就完成了。下一节你会在 React hook 中使用这些函数。

如何构建翻译 Hook

创建 hooks/use-translation.ts。它会运行整个流程(检测、检查、翻译),并暴露 React 状态:

"use client";

import { useCallback, useEffect, useRef, useState } from "react";
import { AUTO } from "@/lib/languages";
import {
  CONFIDENCE_THRESHOLD,
  LowConfidenceError,
  describeError,
  destroyAll,
  detectLanguage,
  getTranslator,
  type Detection,
} from "@/lib/chrome-ai";

export type Phase = "idle" | "detecting" | "preparing" | "translating";

export function useTranslation() {
  const [phase, setPhase] = useState<Phase>("idle");
  const [downloadProgress, setDownloadProgress] = useState<number | null>(null);
  const [output, setOutput] = useState("");
  const [detected, setDetected] = useState<Detection | null>(null);
  const [error, setError] = useState<string | null>(null);
  const controllerRef = useRef<AbortController | null>(null);

  // 在组件卸载时释放模型资源。
  useEffect(() => {
    return () => {
      controllerRef.current?.abort();
      void destroyAll();
    };
  }, []);

  const translate = useCallback(async (text: string, source: string, target: string) => {
    controllerRef.current?.abort();
    const controller = new AbortController();
    controllerRef.current = controller;
    const { signal } = controller;

    setError(null);
    setOutput("");
    setDetected(null);
    setDownloadProgress(null);

    try {
      let from = source;

      if (source === AUTO) {
        setPhase("detecting");
        const result = await detectLanguage(text, setDownloadProgress, signal);
        if (!result || result.confidence < CONFIDENCE_THRESHOLD) throw new LowConfidenceError();
        setDetected(result);
        from = result.language;
      }

      if (from === target) {
        throw new Error("源语言与目标语言相同。");
      }

      setPhase("preparing");
      setDownloadProgress(null);
      const translator = await getTranslator(from, target, setDownloadProgress, signal);

      setPhase("translating");
      setDownloadProgress(null);
      // 流式输出会在文本就绪时立即显示,对于较长的输入感觉更快。
      const reader = translator.translateStreaming(text, { signal }).getReader();
      for (;;) {
        const { done, value } = await reader.read();
        if (done) break;
        setOutput((current) => current + value);
      }
    } catch (caught) {
      if (!signal.aborted) setError(describeError(caught));
    } finally {
      if (controllerRef.current === controller) {
        controllerRef.current = null;
        setPhase("idle");
        setDownloadProgress(null);
      }
    }
  }, []);

  const cancel = useCallback(() => controllerRef.current?.abort(), []);

  const reset = useCallback(() => {
    setOutput("");
    setDetected(null);
    setError(null);
  }, []);

  return { phase, downloadProgress, output, detected, error, translate, cancel, reset };
}

用户点击翻译按钮后,流程如下:

  1. 取消未完成的请求,创建一个新的 AbortController。它的 signal 会传入每次调用,一次 cancel() 就能同时停止语言检测、模型下载和翻译。
  2. 必要时检测语言。当源语言选择“自动检测”时,调用 detectLanguage()。如果结果为 null 或低于置信度阈值,抛出 LowConfidenceError,用户会看到“请手动选择源语言”的提示。
  3. 校验。把一种语言翻译成它自己毫无意义,所以直接终止并给出明确提示。
  4. 准备翻译器。这一步可能触发语言包下载,所以 downloadProgress 会驱动进度条更新。
  5. 流式翻译。使用 translateStreaming(),把每个 chunk 追加到输出结果中。我测试了一段四句话的文本,Chrome 每句话返回一个 chunk。官方文档也建议长文本使用流式方式。句子很短时只会返回一个 chunk,效果和 translate() 一样。

注意,我们用 getReader() 而不是 for await 来读取流。对 ReadableStream 使用 for await 需要 TypeScript 的 dom.asynciterable 库,而 getReader() 到处都能用。

finally 块只有在当前调用仍是最新一次时才重置 UI。没有这个检查的话,一个被取消的旧请求可能会重置新请求的状态。

useEffect 的清理函数会在组件卸载时中止所有未完成的工作并调用 destroyAll(),释放模型资源。

如何构建界面

安全地处理服务端渲染

创建 components/translator-app.tsx。首先要决定的是:在服务端渲染的应用里,如何检测浏览器是否支持该功能。

不能在渲染期间调用 isBuiltInAISupported()。否则服务端会返回 false,浏览器返回 true,React 会报 hydration 不匹配错误。useSyncExternalStore 可以干净地解决这个问题,因为它允许为服务端单独提供快照:

const supported = useSyncExternalStore<boolean | null>(
  noopSubscribe,
  isBuiltInAISupported, // 客户端快照
  () => null,           // 服务端快照
);

服务端和首次客户端渲染看到的都是 null,两者保持一致。随后,React 会在客户端切换到真实结果。当值为 null 时,应用显示“正在检查浏览器支持…”;为 false 时,显示提示信息;为 true 时,显示翻译器。由于浏览器支持状态在页面打开期间不会变化,因此不需要订阅,noopSubscribe 什么都不做。

不支持的提示信息

对于没有相关 API 的浏览器,会显示清晰的说明,而不是一个损坏的表单。创建 components/unsupported-notice.tsx:

export function UnsupportedNotice() {
  return (
    <div className="notice" role="alert">
      <h2>此浏览器不支持 Chrome 内置翻译</h2>
      <p>
        Translator 和 Language Detector API 在桌面版 Chrome(138 及更高版本)中可用。
        它们不支持移动端、Firefox 或 Safari。
      </p>
      <p>
        请在桌面版 Chrome 中打开此页面,或查阅{" "}
        <a href="https://developer.chrome.com/docs/ai/translator-api">Chrome 文档</a>了解这些 API。
      </p>
    </div>
  );
}

语言选择器

创建 components/language-select.tsx。一个通过 htmlFor 关联真实 <label> 的控件可以增强可访问性,并扩大点击区域:

import { AUTO, LANGUAGES } from "@/lib/languages";

interface Props {
  id: string;
  label: string;
  value: string;
  onChange: (code: string) => void;
  /** Adds a "Detect language" option (source selector only). */
  allowAuto?: boolean;
}

export function LanguageSelect({ id, label, value, onChange, allowAuto }: Props) {
  return (
    <div className="field">
      <label htmlFor={id}>{label}</label>
      <select id={id} value={value} onChange={(event) => onChange(event.target.value)}>
        {allowAuto && <option value={AUTO}>Detect language</option>}
        {LANGUAGES.map((language) => (
          <option key={language.code} value={language.code}>
            {language.name}
          </option>
        ))}
      </select>
    </div>
  );
}

文本面板

创建 components/text-panel.tsx。这个组件同时用作输入区和输出区,包含设计稿中的复制和朗读按钮:

"use client";

import { useState } from "react";

interface Props {
  id: string;
  label: string;
  value: string;
  /** 文本的 BCP 47 语言代码,供屏幕阅读器和语音合成使用正确的声音。 */
  lang?: string;
  rtl?: boolean;
  readOnly?: boolean;
  placeholder?: string;
  onChange?: (value: string) => void;
}

export function TextPanel({ id, label, value, lang, rtl, readOnly, placeholder, onChange }: Props) {
  const [copied, setCopied] = useState(false);

  async function copy() {
    await navigator.clipboard.writeText(value);
    setCopied(true);
    setTimeout(() => setCopied(false), 1500);
  }

  function speak() {
    // Web Speech API 独立于内置 AI 接口,在大多数浏览器中均可用。
    speechSynthesis.cancel();
    const utterance = new SpeechSynthesisUtterance(value);
    if (lang) utterance.lang = lang;
    speechSynthesis.speak(utterance);
  }

  return (
    <div className="field">
      <label htmlFor={id} className="visually-hidden">
        {label}
      </label>
      <textarea
        id={id}
        rows={6}
        value={value}
        lang={lang}
        // dir="auto" 允许浏览器根据用户输入的内容自动决定文本方向。
        dir={readOnly ? (rtl ? "rtl" : "ltr") : "auto"}
        readOnly={readOnly}
        placeholder={placeholder}
        onChange={(event) => onChange?.(event.target.value)}
      />
      <div className="actions">
        <button type="button" className="icon" onClick={copy} disabled={!value} aria-label={`Copy ${label.toLowerCase()}`}>
          {copied ? "✓" : "⧉"}
        </button>
        <button type="button" className="icon" onClick={speak} disabled={!value} aria-label={`Read ${label.toLowerCase()} aloud`}>
          🔊
        </button>
      </div>
    </div>
  );
}

以下是一些细节说明:

  • 复制功能使用了 Clipboard API。
  • 朗读功能使用了 Web Speech API 中的 speechSynthesis。它是独立于内置 AI 接口的浏览器功能,支持大多数浏览器。我们设置 utterance.lang 以便浏览器选择匹配的声音。
  • 在输入框上设置 dir="auto" 允许浏览器根据用户输入的内容自动选择文本方向,因此输入阿拉伯文时无需额外逻辑处理。
  • 输出使用了目标语言的 lang 和 dir 属性,这样屏幕阅读器能正确朗读,RTL(从右到左)文字也能正常显示。
  • 两个按钮都设置了 aria-label,因为它们界面上显示的只是图标。

整合起来

下面是主要组件:

"use client";

import { useState, useSyncExternalStore } from "react";
import { useTranslation } from "@/hooks/use-translation";
import { isBuiltInAISupported } from "@/lib/chrome-ai";
import { AUTO, isRtl, languageName } from "@/lib/languages";
import { LanguageSelect } from "./language-select";
import { TextPanel } from "./text-panel";
import { UnsupportedNotice } from "./unsupported-notice";

const noopSubscribe = () => () => {};

export function TranslatorApp() {
  // 在服务器端及水合(hydration)期间返回 `null`,客户端随后获取真实支持状态。
  // 服务器无法预知浏览器支持能力,此做法可避免水合不一致问题。
  const supported = useSyncExternalStore<boolean | null>(
    noopSubscribe,
    isBuiltInAISupported,
    () => null,
  );

  const { phase, downloadProgress, output, detected, error, translate, cancel, reset } =
    useTranslation();

  const [source, setSource] = useState(AUTO);
  const [target, setTarget] = useState("es");
  const [text, setText] = useState("");

  if (supported === null) return <p className="status">正在检查浏览器支持…</p>;
  if (!supported) return <UnsupportedNotice />;

  const busy = phase !== "idle";
  const sourceLang = source === AUTO ? detected?.language : source;

  const statusMessage = (() => {
    if (error) return error;
    if (phase === "detecting") return "正在检测语言…";
    if (phase === "preparing") return "正在准备翻译引擎…";
    if (phase === "translating") return "正在翻译…";
    if (detected && source === AUTO) {
      return `检测到 ${languageName(detected.language)}(置信度 ${Math.round(detected.confidence * 100)}%)。`;
    }
    return "";
  })();

  function swap() {
    if (!sourceLang) return;
    setSource(target);
    setTarget(sourceLang);
    setText(output);
    reset();
  }

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        // 此逻辑运行在点击事件回调中,Chrome 会将其识别为“用户激活”(user activation)。
        // 下载模型前必须具备该激活状态。
        void translate(text.trim(), source, target);
      }}
    >
      <div className="grid">
        <div className="column">
          <LanguageSelect
            id="source-language"
            label="源语言"
            value={source}
            onChange={(code) => {
              setSource(code);
              reset();
            }}
            allowAuto
          />
          <TextPanel
            id="source-text"
            label="源文本"
            value={text}
            lang={sourceLang}
            placeholder="输入或粘贴文本…"
            onChange={setText}
          />
        </div>

        <button
          type="button"
          className="swap"
          onClick={swap}
          disabled={busy || !sourceLang}
          aria-label="交换语言"
          title="交换语言"
        >
          ⇄
        </button>

        <div className="column">
          <LanguageSelect id="target-language" label="目标语言" value={target} onChange={setTarget} />
          <TextPanel
            id="translation"
            label="译文"
            value={output}
            lang={target}
            rtl={isRtl(target)}
            readOnly
            placeholder="译文将显示在此处。"
          />
        </div>
      </div>

      <div className="submit-row">
        {busy ? (
          <button type="button" className="secondary" onClick={cancel}>
            取消
          </button>
        ) : (
          <button type="submit" disabled={!text.trim()}>
            翻译
          </button>
        )}
      </div>

      {downloadProgress !== null && (
        <label className="progress">
          正在下载语言包… {Math.round(downloadProgress * 100)}%
          <progress max={1} value={downloadProgress} />
        </label>
      )}

      {/* 实时区域(live region)将状态变更与错误信息播报给屏幕阅读器。 */}
      <p role="status" aria-live="polite" className={error ? "status error" : "status"}>
        {statusMessage}
      </p>
    </form>
  );
}

有几个细节值得注意。

表单的 onSubmit 处理函数会调用 translate()。由于它在提交表单的点击事件中运行,Chrome 能检测到用户激活状态——这是 Chrome 允许启动模型下载的前提。如果在页面加载时通过 useEffect 调用 Translator.create(),就没有用户手势了。

交换按钮用于对调两种语言,并把翻译结果移入输入框。如果源语言是"检测语言",它会使用实际检测到的语言,且在检测出结果之前该按钮处于禁用状态。

状态行是一个 <p role="status" aria-live="polite">。屏幕阅读器可以在不移动焦点的情况下播报"翻译中…"、检测结果和错误信息。进度条也有可见的标签。

页面与布局

最后,把它接入应用。app/page.tsx 是一个渲染客户端组件的 Server Component:

import { TranslatorApp } from "@/components/translator-app";

export default function Home() {
  return (
    <main>
      <h1>Translate with Chrome&apos;s built-in AI</h1>
      <p className="lede">
        Text is detected and translated on your device by Chrome. It isn&apos;t sent to a
        translation server.
      </p>
      <TranslatorApp />
    </main>
  );
}

然后是 app/layout.tsx:

import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "Translate with Chrome's built-in AI",
  description:
    "A Next.js app that translates text on-device using Chrome's Translator and Language Detector APIs.",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

CSS 就不在这里贴出来了,因为它和这些 API 没有任何关系。直接从仓库复制 app/globals.css 即可,它负责双栏布局、按钮和进度条的样式,在小屏幕上会自动收起为单栏。

注意这个边界:app/page.tsx 和 app/layout.tsx 是 Server Components,而 translator-app.tsx 以 "use client" 开头,所以它和它引入的所有模块都在浏览器里运行。这个边界位置是合理的,因为凡是涉及 Chrome API 的代码都必须在客户端运行。

如何运行和测试应用

启动开发服务器,然后在桌面版 Chrome 中打开对应地址:

npm run dev

接着试试下面这些场景。以下是在 macOS 上的 Chrome 156 中观察到的结果:

操作 结果
输入 "This is a test sentence.",源语言设为 检测语言,目标语言为 西班牙语 检测出 "English(置信度 100%)",并翻译为 "Esta es una oración de prueba."
选择一个之前没用过的语言对(英语到法语) 下载语言包时进度条逐渐增长,在我的网络环境下大约花了 15 秒,随后显示翻译结果。
把一句西班牙语翻译成英语 检测出 "Spanish(置信度 100%)",返回 "Hello, how are you today? I hope everything goes well."
输入一句豪萨语 Chrome 的检测器识别出了它(ha),但翻译器提示不支持从 ha 翻译成英语。

豪萨语这个结果很说明问题:语言检测和语言翻译支持的语言集合并不相同。Chrome 的翻译器列表里没有豪萨语、约鲁巴语或伊博语,要支持这些语言就得换一种方案,比如服务端模型或云端翻译 API。

另外,还可以试试这些边界情况:

  • 在语言包下载过程中点击 Cancel。
  • 在选中 检测语言 的情况下只输入一个单词。短文本的语言检测可靠性差很多,应用可能会让你手动指定语言。
  • 两边选择相同的语言。

如果你在全新的 Chrome 配置文件中首次运行时收到“无法准备此翻译”的提示,稍等片刻再重试即可。我在全新配置文件中第一次运行时,Chrome 抛出了 NotSupportedError,第二次尝试才成功,这也是 describeError 会解释错误原因、而不是归咎于语言本身的原因。

局限性与生产环境注意事项

内置 AI API 让翻译代码变得非常精简,但它们也带来了一些限制,需要提前规划。

浏览器支持

这些是 Chrome(和 Edge)桌面版专属的功能,应把它们当作渐进增强来对待:

  • 使用前先用 "Translator" in self 做特性检测,就像前面的示例那样。
  • 为其他浏览器提供降级方案,比如云端翻译 API,并告知用户文本何时会离开设备。
  • 不要让整个产品的其他功能都依赖这项特性。

隐私

“隐私”的含义要说清楚:

  • 翻译和语言检测都在本地运行。文本不会被发送到翻译 API。
  • 模型下载仍然需要联网。首次使用某个语言对时,Chrome 会从网络下载语言包。
  • 确保你自己的数据统计和错误日志永远不会记录用户翻译的文本。

质量与诚实

  • 语言检测是概率性的。要展示置信度、设置阈值,并允许用户手动修正。
  • Chrome 的文档明确警告:检测器无法百分之百准确地识别所有语言。
  • 法律、医疗、金融等高风险内容不要只依赖机器翻译,发布涉及的语言应让母语者审核译文。

性能与资源

  • 对长输入分块处理。翻译是按顺序执行的,长文本会阻塞排在后面的所有请求。要展示加载状态,并把大文档拆分处理。
  • 检查配额。某些实现会限制输入大小。Translator 暴露了 inputQuota 和 measureInputUsage(),可以在翻译前先检查(这是 MDN 推荐的模式,本示例没有接入):
const translator = await getTranslator("en", "es");
const usage = await translator.measureInputUsage(text);
if (usage > translator.inputQuota) {
  throw new Error("That text is too long to translate in one go.");
}
  • 释放资源。不再需要的 translator 实例要调用 destroy() 销毁,就像 destroyAll() 做的那样。

嵌入与 Worker

  • 这些 API 在 Web Workers 中不可用,所以没法像使用 Transformers.js 那样把任务移出主线程。
  • 跨域 iframe 需要配置 Permissions Policy 的 allow 属性才能使用。

结语

我们构建了一个在设备端本地运行的 Next.js 翻译器,无需托管模型,也无需推理后端。过程中用到了 Translator 和 Language Detector API 的主要功能:特性检测、availability()、带下载进度的 create()、返回置信度的 detect()、translateStreaming()、用 AbortController 取消任务,以及 destroy()。

我们还处理了基于浏览器的 AI 在服务端渲染框架中带来的种种问题:服务端没有 Translator、模型按需下载且需要用户手势触发、仅部分浏览器支持、翻译质量因语言而异。

浏览器端 AI 并不会取代服务端 AI,而是提供了另一种选择——可以降低成本和延迟,让一次性的用户文本留在设备上。在 Chrome 支持的地方,你现在有了一种轻量、基于标准的方式来构建多语言体验。

原始来源: freeCodeCamp

评论 (0)