
用 Chrome 内置 AI API 在 Next.js 中构建一个可流式输出的翻译器
用 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 驱动的翻译则是为那些没有人提前写好的内容即时生成译文,比如评论、评价、客服消息和帖子。
| 传统 i18n | AI 翻译 |
|---|---|
| 使用预定义的译文 | 动态生成译文 |
| 适合界面文案 | 适合用户生成内容 |
| 通常由开发者维护 | 可处理任意文本 |
| 输出可预测 | 输出可能变化 |
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 中打开它,然后:
- 把几句不同语言的文字粘贴到语言检测器里,观察置信度分数。
- 先试一个单词,再试一整句。短输入会得到低准确度的结果,对比一下置信度数值就能看出来。
- 在几组语言对之间做翻译。某个语言对的第一次翻译可能会停顿,因为 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,按下面的顺序验证:
- 输入一句英语,源语言保持「自动检测」,目标语言选西班牙语,点翻译。第一次会看到语言包下载进度,之后译文开始流式出现。
- 在下载过程中点取消,确认进度条消失、不再有新的译文写入。
- 输入一个单词,观察是否触发低置信度提示,再手动选择源语言重试。
- 把目标语言换成阿拉伯语,确认译文面板按从右到左排版。
- 点复制,粘贴到别处确认内容一致;点朗读,确认按目标语言发音。
- 点互换语言,确认源语言与目标语言、输入与译文都交换了。
- 用 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 官方当前信息为准。