AB
AiBoss
Tutorials

用 Chrome 内置 AI API 在 Next.js 中构建一个可流式输出的翻译器

Tutorials

用 Chrome 内置 AI API 在 Next.js 中构建一个可流式输出的翻译器

Chrome 内置的 Translator 与 Language Detector API 让翻译在用户设备上完成,不必自建推理服务、也不按请求计费。本教程用 Next.js 搭建一个翻译器:自动识别语言、按语言对翻译并流式渲染、显示语言包下载进度并支持取消、复制与朗读译文、互换源语言与目标语言,并对不支持的浏览器给出提示。

大多数翻译功能的实现方式都一样:用户输入文字,应用把文字发给翻译 API,API 返回译文。这样能跑通,但每一次请求都带来成本与延迟,而且用户的文字离开了他们的设备。Chrome 现在提供了两个内置 AI API 来改变这一点:Translator API 与 Language Detector API。Chrome 按需下载小型专用模型,并在用户设备上运行。你不需要托管模型、不需要运行推理服务器、也不需要按请求付费,只需要调用一个 JavaScript API。

本教程会带你用 Next.js 构建一个翻译器,它能做到:识别用户输入文字的语言;把文字翻译成用户选择的语言;在 Chrome 生成译文的过程中把结果流式写入页面;显示语言包下载进度并允许用户取消;复制译文、朗读译文、互换两种语言;对不支持这些 API 的浏览器做降级处理。

准备工作

在动手之前,先确认环境与知识储备。

你需要熟悉:

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

你需要准备:

  • Node.js 20.9 或更高版本
  • 桌面版 Chrome 138 或更高版本

Translator 与 Language Detector API 只在桌面版 Chrome 中可用,移动设备上不可用,Firefox 与 Safari 也不支持。Chrome 的浏览器支持表里还列出了 Edge。你不需要了解任何机器学习知识。

另外要说明一点:这些 API 的可用语言列表、浏览器版本要求、模型下载行为都可能随 Chrome 版本变化,具体以 Chrome 官方当前信息为准。

先分清国际化与 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 驱动的翻译则是为那些没有人提前写好的内容即时生成译文,比如评论、评价、客服消息和帖子。

传统 i18nAI 翻译
使用预定义的译文动态生成译文
适合界面文案适合用户生成内容
通常由开发者维护可处理任意文本
输出可预测输出可能变化

AI 翻译是对 i18n 的补充,不是替代。按钮和菜单仍然需要人工维护的文案,Translator API 填补的是其余部分。一个典型场景是客服聊天:用户用母语写消息,站点在消息离开用户设备之前,把它翻译成客服所用的语言。

Chrome 内置 AI API 的工作方式

两个 API 配合使用:

  • LanguageDetector 接收文本,返回一个按可能性排序的语言列表,每项带 0 到 1 之间的置信度分数。
  • Translator 针对某一对语言(例如英语到西班牙语)创建,并在两者之间翻译文本。

与调用云端 API、或用 Transformers.js 之类的库自己跑模型相比,区别在于:

  • 模型归浏览器所有。你不打包、不托管模型文件,Chrome 在站点第一次需要时下载它们。
  • 翻译使用语言包。语言包可以理解成某种语言的词典,按需下载。某一语言对的第一次翻译会触发下载,之后的翻译复用已下载的语言包。
  • 一切都是异步且带权限感知的。先调用 availability(),再调用 create(),并且可以监听下载进度。

有四条约束需要在设计时考虑进去:

  • 需要用户激活。当模型需要下载时,创建 translator 或 detector 需要一次用户手势,例如点击。
  • 不能在 Web Worker 中使用。两个 API 在 worker 里都不可用,因此要从主线程调用。调用是异步的,模型在你的 JavaScript 线程之外运行,所以不会阻塞界面。
  • 顺序处理。翻译按顺序逐个处理,一个大请求会阻塞后面的请求,因此要分块处理并显示加载指示。
  • 仅限顶层窗口。默认情况下,API 在顶层窗口和同源 iframe 中工作;跨源 iframe 需要 Permissions Policy 的 allow 属性。

两个 API 的 availability() 方法都返回四种值之一,界面应当分别处理:

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

还有一个隐私细节:Chrome 会隐藏特定语言对的下载状态以保护用户隐私。在你的站点为某个语言对创建 translator 之前,所有语言对都会报告为 downloadable。

先在 Playground 里试一下

写代码之前先做实验。Chrome 的 Built-in AI Playground 把 Chrome 以 JavaScript API 形式暴露的 AI 功能集中展示出来,其中就包括这两个 API。

在桌面版 Chrome 中打开它,然后:

  1. 把几句不同语言的文字粘贴到语言检测器里,观察置信度分数。
  2. 先试一个单词,再试一整句。短输入会得到低准确度的结果,对比一下置信度数值就能看出来。
  3. 在几组语言对之间做翻译。某个语言对的第一次翻译可能会停顿,因为 Chrome 正在下载语言包。

接下来要构建的应用,正是把这种行为做进去。

操作步骤

第 1 步:创建 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 及相关类型,因此不需要 import。编辑器现在能自动补全 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/ 放界面;app/ 放 Next.js 的页面与布局。

第 2 步:定义语言列表

创建 lib/languages.ts,列出 Translator API 支持的语言。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 },
  // ...完整列表见项目仓库
  { 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 标记让阿拉伯语和希伯来语的译文按从右到左渲染。

第 3 步:封装 Chrome API

创建 lib/chrome-ai.ts。这个文件是项目的核心,所有对 Translator 与 Language Detector 的调用都集中在这里,应用其余部分不直接接触它们。文件里的代码只在浏览器中运行,因此要从客户端组件里 import。

先写共享常量、类型与错误类:

/**
 * Thin helpers around Chrome's built-in Translator and Language Detector APIs.
 * Everything here runs in the browser only. Import it from Client Components.
 */

/** Below this confidence we ask the user to pick the language instead of guessing. */
export const CONFIDENCE_THRESHOLD = 0.6;

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

export class LowConfidenceError extends Error {
  constructor() {
    super("We couldn't tell which language this is. Choose the source language manually.");
  }
}

export class UnsupportedPairError extends Error {
  constructor(source: string, target: string) {
    super(`Chrome can't translate from "${source}" to "${target}" on this device.`);
  }
}

各部分的作用:

  • CONFIDENCE_THRESHOLD 是语言检测器可接受的最低置信度。检测是概率而非事实,短句和单词的准确度很低,置信度不足时应把结果当作未知。后面写的 hook 会把每个结果与这个数值比较。0.6 只是起点,可以按自己的用户调整。
  • DownloadProgress 是接收下载进度的回调类型。Chrome 以 0 到 1 的分数报告进度,0.5 表示语言包下载了一半。
  • LowConfidenceError 在检测器无法判断语言时抛出。给它单独的类,hook 就能把它与其他失败区分开,它的消息也告诉用户下一步该做什么。
  • UnsupportedPairError 在 Chrome 表示无法在两种语言之间翻译时抛出,消息里带上两个语言代码,用户就知道是哪一对失败了。

再做特性检测:

/** Feature detection. Always false on the server, where `self.Translator` doesn't exist. */
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 检测。应用两个都需要,所以只有两者都存在时才报告支持。函数返回 true 或 false,从不抛错。后面用它决定显示翻译器还是「不支持」提示。

封装语言检测:

export async function detectLanguage(text: string): Promise<string> {
  const availability = await LanguageDetector.availability();
  if (availability === "unavailable") {
    throw new Error("Language detection is not available in this browser.");
  }

  const detector = await LanguageDetector.create();
  const results = await detector.detect(text);
  detector.destroy();

  const best = results[0];
  if (!best || best.confidence < CONFIDENCE_THRESHOLD) {
    throw new LowConfidenceError();
  }
  return best.detectedLanguage;
}

要点:先查 availability();create() 之后用 detect() 拿到排序结果;用完调用 destroy() 释放资源;置信度低于阈值时抛出 LowConfidenceError,让界面提示用户手动选择源语言。

封装翻译与流式输出:

export async function createTranslator(
  sourceLanguage: string,
  targetLanguage: string,
  onProgress?: DownloadProgress,
) {
  const availability = await Translator.availability({
    sourceLanguage,
    targetLanguage,
  });

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

  return Translator.create({
    sourceLanguage,
    targetLanguage,
    monitor(m) {
      m.addEventListener("downloadprogress", (event) => {
        onProgress?.(event.loaded);
      });
    },
  });
}

这里把 availability() 的四种返回值都考虑进去:unavailable 直接抛 UnsupportedPairError;downloadable 与 downloading 会在 create() 时触发或继续下载,并通过 monitor 回调把进度传出去;available 则直接创建成功。

流式翻译用 translateStreaming(),它返回一个可读流,每生成一段就推一段:

export async function translateStreaming(
  translator: Awaited<ReturnType<typeof createTranslator>>,
  text: string,
  onChunk: (chunk: string) => void,
): Promise<string> {
  const stream = translator.translateStreaming(text);
  const reader = stream.getReader();
  let full = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    full += value;
    onChunk(value);
  }

  return full;
}

因为翻译是顺序处理的,长文本会阻塞后续请求,所以界面层要把输入分块,并在处理期间显示加载状态。

第 4 步:编写翻译 hook

创建 hooks/use-translation.ts,把上面的纯函数变成 React 状态。它需要管理:源语言(可以是 AUTO)、目标语言、输入文本、译文、是否正在翻译、下载进度、错误信息,以及一个用于取消的 AbortController。

"use client";

import { useCallback, useRef, useState } from "react";
import { AUTO } from "@/lib/languages";
import {
  LowConfidenceError,
  UnsupportedPairError,
  createTranslator,
  detectLanguage,
  translateStreaming,
} from "@/lib/chrome-ai";

export function useTranslation() {
  const [source, setSource] = useState(AUTO);
  const [target, setTarget] = useState("es");
  const [input, setInput] = useState("");
  const [output, setOutput] = useState("");
  const [busy, setBusy] = useState(false);
  const [progress, setProgress] = useState<number | null>(null);
  const [error, setError] = useState<string | null>(null);
  const abortRef = useRef<AbortController | null>(null);

  const cancel = useCallback(() => {
    abortRef.current?.abort();
    abortRef.current = null;
    setBusy(false);
    setProgress(null);
  }, []);

  const translate = useCallback(async () => {
    if (!input.trim()) return;
    const controller = new AbortController();
    abortRef.current = controller;
    setBusy(true);
    setError(null);
    setOutput("");
    setProgress(null);

    try {
      const from = source === AUTO ? await detectLanguage(input) : source;
      if (controller.signal.aborted) return;

      const translator = await createTranslator(from, target, (fraction) => {
        setProgress(fraction);
      });
      if (controller.signal.aborted) {
        translator.destroy();
        return;
      }
      setProgress(null);

      await translateStreaming(translator, input, (chunk) => {
        if (!controller.signal.aborted) {
          setOutput((previous) => previous + chunk);
        }
      });
      translator.destroy();
    } catch (caught) {
      if (controller.signal.aborted) return;
      if (caught instanceof LowConfidenceError) {
        setError("无法判断语言,请手动选择源语言。");
      } else if (caught instanceof UnsupportedPairError) {
        setError("当前设备不支持这一对语言的翻译。");
      } else {
        setError(caught instanceof Error ? caught.message : "翻译失败。");
      }
    } finally {
      if (!controller.signal.aborted) setBusy(false);
    }
  }, [input, source, target]);

  return {
    source, setSource,
    target, setTarget,
    input, setInput,
    output,
    busy, progress, error,
    translate, cancel,
  };
}

几个设计点:source === AUTO 时先检测语言,检测结果只用于本次翻译,不写回下拉框;每次翻译前清空译文与进度;取消时通过 AbortController 让后续的 chunk 不再写入状态,并销毁已创建的 translator;错误按类型分别给出可操作的提示。

第 5 步:构建界面

界面拆成四个组件。

components/language-select.tsx:一个受控的下拉框,遍历 LANGUAGES 渲染选项。源语言下拉框额外包含 AUTO 选项,文案类似「自动检测」。

"use client";

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

export function LanguageSelect({
  value,
  onChange,
  includeAuto = false,
  label,
}: {
  value: string;
  onChange: (value: string) => void;
  includeAuto?: boolean;
  label: string;
}) {
  return (
    <label>
      {label}
      <select value={value} => onChange(event.target.value)}>
        {includeAuto && <option value={AUTO}>自动检测</option>}
        {LANGUAGES.map((language) => (
          <option key={language.code} value={language.code}>
            {language.name}
          </option>
        ))}
      </select>
    </label>
  );
}

components/text-panel.tsx:一个带 dir 属性的文本区域,用于输入或展示译文。译文面板根据 isRtl(target) 设置 dir="rtl",阿拉伯语与希伯来语才能正确排版。

"use client";

export function TextPanel({
  value,
  onChange,
  readOnly = false,
  rtl = false,
  placeholder,
}: {
  value: string;
  onChange?: (value: string) => void;
  readOnly?: boolean;
  rtl?: boolean;
  placeholder?: string;
}) {
  return (
    <textarea
      dir={rtl ? "rtl" : "ltr"}
      value={value}
      readOnly={readOnly}
      placeholder={placeholder} => onChange?.(event.target.value)}
    />
  );
}

components/unsupported-notice.tsx:当 isBuiltInAISupported() 返回 false 时显示。文案说明需要桌面版 Chrome,并建议改用其他浏览器或设备。

components/translator-app.tsx:把上面这些拼起来。它是客户端组件,挂载后先做特性检测,再渲染语言选择、输入面板、操作按钮与译文面板。按钮区包括:翻译、取消(仅在 busy 时出现)、复制、朗读、互换语言。

  • 复制:调用 navigator.clipboard.writeText(output)。
  • 朗读:用 speechSynthesis 以目标语言的 BCP 47 代码作为 utterance.lang 朗读译文。
  • 互换语言:把当前 target 设为新的 source,把原来的 source(若为 AUTO 则用检测到的语言)设为新的 target,同时交换输入与译文。
  • 下载进度:progress 不为 null 时显示进度条,数值为 Math.round(progress * 100),旁边放取消按钮。
"use client";

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

export function TranslatorApp() {
  const [supported, setSupported] = useState<boolean | null>(null);
  const t = useTranslation();

  useEffect(() => {
    setSupported(isBuiltInAISupported());
  }, []);

  if (supported === null) return null;
  if (!supported) return <UnsupportedNotice />;

  return (
    <main>
      <LanguageSelect label="源语言" value={t.source} includeAuto />
      <LanguageSelect label="目标语言" value={t.target} />

      <TextPanel value={t.input} placeholder="输入要翻译的文字" />

      <button disabled={t.busy}>翻译</button>
      {t.busy && <button

      {t.progress !== null && (
        <p>正在下载语言包:{Math.round(t.progress * 100)}%</p>
      )}
      {t.error && <p role="alert">{t.error}</p>}

      <TextPanel value={t.output} readOnly rtl={isRtl(t.target)} />

      <button => navigator.clipboard.writeText(t.output)}>复制</button>
      <button => {
          const utterance = new SpeechSynthesisUtterance(t.output);
          utterance.lang = t.target;
          speechSynthesis.speak(utterance);
        }}
      >
        朗读
      </button>
    </main>
  );
}

最后把 app/page.tsx 改成渲染 <TranslatorApp />,并在 app/layout.tsx 里保留全局样式与元数据。

第 6 步:运行与测试

启动开发服务器:

npm run dev

在桌面版 Chrome 中打开 http://localhost:3000,按下面的顺序验证:

  1. 输入一句英语,源语言保持「自动检测」,目标语言选西班牙语,点翻译。第一次会看到语言包下载进度,之后译文开始流式出现。
  2. 在下载过程中点取消,确认进度条消失、不再有新的译文写入。
  3. 输入一个单词,观察是否触发低置信度提示,再手动选择源语言重试。
  4. 把目标语言换成阿拉伯语,确认译文面板按从右到左排版。
  5. 点复制,粘贴到别处确认内容一致;点朗读,确认按目标语言发音。
  6. 点互换语言,确认源语言与目标语言、输入与译文都交换了。
  7. 用 Firefox 或 Safari 打开同一页面,确认显示「不支持」提示而不是报错。

一个完整示例

下面把关键文件串成一个最小可运行版本,便于对照检查。目录结构沿用前面的约定。

lib/languages.ts:至少包含 AUTO、LANGUAGES、languageName、isRtl 四个导出,语言列表按需裁剪,但 zh、zh-Hant、ar、he 建议保留,用来验证 RTL。

lib/chrome-ai.ts:包含 CONFIDENCE_THRESHOLD、DownloadProgress、LowConfidenceError、UnsupportedPairError、isBuiltInAISupported、detectLanguage、createTranslator、translateStreaming。

hooks/use-translation.ts:暴露 source、target、input、output、busy、progress、error、translate、cancel 以及对应的 setter。

app/page.tsx:

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

export default function Page() {
  return <TranslatorApp />;
}

完整流程是:页面挂载 → isBuiltInAISupported() 判断 → 用户输入并点击翻译 → 若源语言为 AUTO 则 detectLanguage() → createTranslator() 检查可用性并可能下载语言包 → translateStreaming() 逐块写入译文 → 用户可复制、朗读、互换语言或取消。任何一步失败都会落到 error 状态并显示对应提示。

注意事项

平台限制。两个 API 只在桌面版 Chrome 中可用,移动设备不支持,Firefox 与 Safari 也不支持。Chrome 的支持表里还列出了 Edge。版本要求与支持范围会随浏览器更新变化,以官方当前信息为准。

用户激活。当模型需要下载时,创建 translator 或 detector 需要一次用户手势。不要在页面加载时自动创建,否则可能失败。

不能在 Web Worker 中调用。两个 API 都只能在主线程使用。调用本身是异步的,模型在 JavaScript 线程之外运行,所以不会阻塞界面,但不要把重活同步堆在主线程上。

顺序处理。翻译逐个处理,一个大请求会阻塞后面的请求。长文本要分块,并在处理期间显示加载指示。

仅限顶层窗口。默认只在顶层窗口和同源 iframe 中工作,跨源 iframe 需要 Permissions Policy 的 allow 属性。

语言列表可能变化。Chrome 说明支持的语言列表是其实现特有的、可能变化,目前也没有动态获取的函数。因此每次翻译前都要调用 Translator.availability(),硬编码的列表只用于渲染下拉框。

下载状态被隐藏。为保护隐私,Chrome 会隐藏特定语言对的下载状态。在你的站点为某个语言对创建 translator 之前,所有语言对都报告为 downloadable,不要据此判断用户是否已经下载过。

短文本置信度低。单个词或很短的短语检测准确度低,应把低于阈值的检测结果当作未知,提示用户手动选择源语言。阈值 0.6 只是起点,可以按实际用户调整。

资源释放。用完 translator 与 detector 后调用 destroy(),避免长期占用内存。

隐私。翻译在用户设备上完成,文本不会因为翻译请求而离开设备。但页面上的其他网络请求仍可能发送数据,需要单独审查。

成本与配额。这些 API 不按请求计费,也不需要你托管模型,但语言包下载会消耗用户的流量与时间,界面应当把下载进度与取消能力暴露出来。具体行为与限制以 Chrome 官方当前信息为准。