如何用 Chrome 内置 AI 打造本地翻译器
大多数翻译功能的套路都一样:用户输入文字,应用把文字发给翻译 API,API 再返回译文。这样做没问题,但每次请求都有成本和延迟,而且用户的文字还会离开他们的设备。
Chrome 现在内置了两个 AI API,可以改变这一切:Translator API 和 Language Detector API。Chrome 会按需下载小型专用模型,直接在用户设备上运行。你不需要部署模型、搭建推理服务器,也不必按请求付费,只要调用 JavaScript API 就行。
本教程将带你在 Next.js 中构建一个翻译器,它能:
- 自动检测用户输入的文字语言。
- 翻译成用户选择的目标语言。
- 在 Chrome 生成译文的同时流式显示到页面上。
- 展示语言包的下载进度,并支持用户取消下载。
- 复制译文、朗读译文、互换两种语言。
- 妥善处理不支持这些 API 的浏览器。
目录
- 前置要求
- 国际化 vs AI 翻译
- Chrome 内置 AI API 的工作原理
- 先在 Playground 里试用这些 API
- 如何搭建 Next.js 项目
- 如何定义语言列表
- 如何封装 Chrome API
- 如何编写翻译 Hook
- 如何构建界面
- 如何运行和测试应用
- 局限性与生产环境注意事项
- 总结
前置要求
你需要熟悉:
- 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 这类库自己跑模型有以下区别:
- 模型由浏览器管理。你不需要打包或托管模型文件,Chrome 会在网站首次需要时自动下载。
- 翻译使用语言包。Chrome 文档把语言包形容为"某种语言的词典",按需下载。首次翻译某个语言对时会触发下载,之后直接复用。
- 一切皆异步,且受权限控制。先调用
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 中打开并尝试:- 在语言检测器中粘贴几段不同语言的句子,并查看置信度得分。
- 先试单个单词,再试完整句子。Chrome 的文档警告称,短输入会导致结果准确性较低,因此请对比置信度数值。
- 在几组语言对之间进行翻译。对于某语言对的首次翻译,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 文档描述的生命周期,分四步工作:
- 查缓存。一个
Translator只能对应一个语言对,而创建它的开销很大,所以我们用一个Map缓存,以"en>es"这类字符串作为键。如果这个语言对的翻译器已经存在,就直接返回。这也是翻译第二句话时速度快的原因。 - 检查可用性。
Translator.availability()告诉我们 Chrome 能否处理这个语言对,返回值可能是unavailable、downloadable、downloading或available。如果是unavailable,我们会先抛出UnsupportedPairError,避免为永远无法工作的语言对启动下载。 - 创建翻译器。
Translator.create()接收语言对、用于取消的signal,以及一个monitor——它上报下载进度的方式和前面检测器完全一样。如果需要下载语言包,Chrome 会在这里自动开始下载。当需要下载时,这一步还要求有用户手势(比如点击)触发。 - 保存并返回。把新建的翻译器存入
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 };
}
用户点击翻译按钮后,流程如下:
- 取消未完成的请求,创建一个新的
AbortController。它的signal会传入每次调用,一次cancel()就能同时停止语言检测、模型下载和翻译。 - 必要时检测语言。当源语言选择“自动检测”时,调用
detectLanguage()。如果结果为null或低于置信度阈值,抛出LowConfidenceError,用户会看到“请手动选择源语言”的提示。 - 校验。把一种语言翻译成它自己毫无意义,所以直接终止并给出明确提示。
- 准备翻译器。这一步可能触发语言包下载,所以
downloadProgress会驱动进度条更新。 - 流式翻译。使用
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's built-in AI</h1>
<p className="lede">
Text is detected and translated on your device by Chrome. It isn'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 支持的地方,你现在有了一种轻量、基于标准的方式来构建多语言体验。