How to Build a Translator with Chrome’s Built-In AI
TL;DR · AI 摘要
How to Build a Translator with Chrome’s Built-In AI November 17, 2026 / AI David Aniebo Most translation features work t...
核心要点
- 主题聚焦:How to Build a Translator with Chrome’s Built-In
- 来源:freeCodeCamp.org,建议结合原文判断细节。
- AI 分析暂不可用,本条为保底评分与摘要。
如何使用Chrome内置AI构建翻译器
2026年11月17日
/
#AI
David Aniebo
大多数翻译功能的工作方式类似。用户输入文本后,你的应用将其发送到翻译API,然后API返回翻译结果。这种方式虽然可行,但每次请求都会增加成本和延迟,且用户的文本会离开设备。
Chrome现在提供了两个内置AI API,彻底改变了这一现状:Translator API和Language Detector API。Chrome按需下载小型专用模型并在用户设备上运行。你无需托管模型、运行推理服务器或按请求付费,只需调用JavaScript API即可。
在本教程中,你将使用Next.js构建一个翻译器,实现以下功能:
- 检测用户输入文本的语言
- 将其翻译成用户选择的语言
- 以Chrome生成结果的方式实时流式传输翻译内容到页面
- 显示语言包下载进度并允许用户取消
- 复制翻译内容、朗读文本并切换两种语言
- 处理不支持这些API的浏览器
目录
- 先决条件
- 国际化与AI翻译的区别
- Chrome内置AI API的工作原理
- 首先在游乐场尝试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(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的文档提供了一个很好的例子:在支持聊天中,用户用母语书写,你的网站会在消息离开用户设备前将其翻译成客服人员的语言。
- LanguageDetector 接收文本并返回按语言排名的列表,每种语言都有一个 0 到 1 之间的置信度评分。
- Translator 是为特定语言对(例如英语到西班牙语)创建的,用于在它们之间进行翻译。
它们与调用云 API 或使用类似 Transformers.js 的库自行运行模型的不同之处在于:
- 浏览器拥有模型。你不需要打包或托管模型文件。Chrome 会在首次需要时自动下载模型文件。
- 翻译使用语言包。Chrome 的文档将语言包描述为“某种语言的字典”,按需下载。首次翻译某对语言会触发下载,后续翻译会复用已下载的语言包。
- 所有操作都是异步且基于权限的。你需要先调用 availability() 检查可用性,然后调用 create(),并且可以监视下载进度。
你需要围绕以下四个约束进行设计,这些约束均来自 Chrome 的官方文档:
- 用户激活。创建翻译器或检测器需要用户手势(如点击)来触发模型下载。
- 不支持 Web Workers。这两个 API 都无法在 Worker 中使用,因此你必须在主线程中调用它们。(调用是异步的,模型在 JavaScript 线程之外运行,因此不会阻塞 UI。)
- 顺序处理。翻译操作按顺序执行。大请求会阻塞后续操作,因此需要分块处理并显示加载状态。
- 仅限顶层窗口。默认情况下,这些 API 仅在顶层窗口和同源 iframe 中可用。跨域 iframe 需要添加 Permissions Policy 的 allow 属性。
两个 API 的 availability() 方法会返回以下四个值之一,你的 UI 需要针对每个值进行处理:
值 | 含义 --- | --- unavailable | 浏览器不支持这些功能。 downloadable | 支持,但需要先下载模型文件。 downloading | 支持,且下载正在进行中。 available | 支持且无需下载即可使用。
隐私细节:Chrome 会隐藏特定语言对的下载状态以保护用户隐私。在你的网站为某对语言创建翻译器之前,所有语言对都会被报告为 downloadable。
首先在 Playground 中尝试这些 API
在编写代码之前,先进行实验。Built-in AI Playground 展示了 Chrome 作为 JavaScript API 暴露的 AI 功能,包括这两个 API。在桌面版 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 定义。由于 Translator 和 LanguageDetector 不在标准 DOM 类型中,TypeScript 目前还不知道它们:
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/ 包含用户界面组件。
- app/ 包含 Next.js 页面和布局。
如何定义语言
创建 lib/languages.ts。该文件列出 Chrome 翻译器 API 支持的语言(来自 Chrome 官方文档)。翻译器 API 使用 BCP 47 编码如 es 或 zh-Hant:
/** 表示"让我检测源语言"的哨兵值。 */
export const AUTO = "auto";
export interface Language {
/** 翻译器 API 期望的 BCP 47 编码。 */
code: string;
name: string;
rtl?: boolean;
}
export const LANGUAGES: Language[] = [
{ code: "ar", name: "阿拉伯语", rtl: true },
{ code: "de", name: "德语" },
{ code: "en", name: "英语" },
{ code: "es", name: "西班牙语" },
{ code: "fr", name: "法语" },
{ code: "he", name: "希伯来语", rtl: true },
// ...完整的39种语言列表在仓库中
{ code: "zh", name: "简体中文" },
{ code: "zh-Hant", name: "繁体中文" },
];
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 翻译器和语言检测器 API 的调用,因此应用其他部分无需直接接触这些 API。
你将逐步构建该文件,每次添加新功能到前一个功能下方。该文件中的所有代码仅在浏览器中运行,因此需要从客户端组件导入。
第一步:添加共享常量、类型和错误
从几个小定义开始,这些定义是后续函数依赖的基础:
/**
* 围绕 Chrome 内置翻译器和语言检测器 API 的轻量级辅助工具。
* 所有代码仅在浏览器中运行,需从客户端组件导入。
*/
/** 低于此置信度时,我们要求用户手动选择语言而非猜测。 */
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(`Chrome can't translate from "${source}" to "${target}" on this device.`);
}
}
每个部分的作用如下:
- CONFIDENCE_THRESHOLD 是语言检测器接受的最低置信度分数。检测是一个概率值,而非绝对事实。Chrome 的文档警告说,非常短的短语和单个单词会导致低精度结果,建议当置信度过低时将结果视为未知。你稍后编写的钩子函数会将每个结果与这个数值进行比较。0.6 是一个起始值,你可以根据自己的用户需求进行调整。
- DownloadProgress 是接收下载进度回调的类型。Chrome 以 0 到 1 的分数报告进度,因此 0.5 表示语言包已下载了一半。
- LowConfidenceError 在检测器无法识别文本语言时抛出。为其单独设置类可以让钩子函数将其与其他错误区分开,其提示信息会告诉用户下一步该怎么做。
- 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 步:创建语言检测器
接下来,添加创建检测器的代码。这是你第一次看到监控回调和下载进度:
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); // 结果按可能性从高到低排序。最后一个条目始终是 "und"(未确定)。 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 步:创建并缓存翻译器
翻译是语言对逻辑的所在地。接下来添加以下内容:
// 翻译器与一种语言对绑定。创建一个翻译器成本较高,因此我们保留它们。 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 文档中描述的生命周期,分为四个阶段:
- 检查缓存。每个翻译器仅对应一种语言对。创建翻译器成本较高,因此我们通过类似"en>es"的字符串作为键值,将其存储在Map中。如果已经存在对应语言对的翻译器,会立即返回该实例。这就是为什么翻译第二句时速度很快的原因。
- 检查可用性。Translator.availability()方法会告诉我们Chrome是否能处理该语言对。该方法返回unavailable、downloadable、downloading或available四种状态。如果返回unavailable,我们会直接抛出UnsupportedPairError错误,而不再尝试其他操作,这样就不会为无法使用的语言对启动下载。
- 创建翻译器。Translator.create()方法接收语言对、取消操作信号以及一个监控器(该监控器会像检测器一样报告下载进度)。如果需要下载语言包,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()操作将不会执行任何操作。
接下来你要编写的钩子函数会在组件卸载时调用destroyAll()方法。
### 第7步:将API错误转换为有用的信息
最后添加一个向用户解释失败原因的函数:
/** 将这些API抛出的DOMExceptions转换为用户可采取操作的信息。 */ 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来报告问题,异常的名称会说明具体发生了什么错误。这个函数会将每个名称映射到用户可以采取操作的信息:
- 不允许错误(NotAllowedError):Chrome 需要用户手势(如点击)来启动下载,但未收到相关操作。让用户再次点击“翻译”即可解决问题。
- 不支持错误(NotSupportedError):MDN 文档指出该错误会在请求的语言不被支持时抛出。在测试中我也在全新 Chrome 剖面的首次尝试时遇到此错误(此时 Chrome 正在准备组件),但第二次尝试就正常了。该提示信息覆盖了这两种情况。
- 配额超出错误(QuotaExceededError):MDN 文档指出该错误会在输入内容超过可用配额时抛出。这意味着文本长度过长。
- 网络错误(NetworkError):语言包无法下载。
对于其他情况,函数会回退到错误对象自身的 message 属性(如果是普通 Error 对象),或显示通用提示信息。
你的 lib/chrome-ai.ts 文件现在已经完成。在下一章节中,你将从 React 钩子中使用这些函数。
## 如何构建翻译钩子
创建 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);
const translate = useCallback( async (text: string) => { 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()并逐块追加到输出中。在我的四句话测试中,Chrome每句话返回一个块。文档建议长文本使用流式传输。对于短句,会得到单个块,行为与translate()相同。
注意我们使用getReader()而不是for await来读取流。for await需要dom.asynciterable TypeScript库,而getReader()在所有环境中都适用。
finally块只有在当前调用仍是最新调用时才会重置UI。如果没有这个检查,被取消的旧请求可能会重置新请求的状态。
useEffect清理会中止所有挂起操作,并在组件卸载时调用destroyAll()释放模型。
## 如何构建界面
### 安全处理服务端渲染
创建components/translator-app.tsx。第一个决策是如何在服务端渲染的应用中检查浏览器支持。
不能在渲染期间调用isBuiltInAISupported()。服务端会返回false,浏览器返回true,React会报告水合不匹配。useSyncExternalStore能干净地解决这个问题,因为它为服务端单独拍摄快照:
const supported = useSyncExternalStore<boolean | null>( noopSubscribe, isBuiltInAISupported, // 客户端快照 () => null, // 服务端快照 );
服务端和首次客户端渲染都会看到null,因此匹配。React随后会在客户端切换到真实答案。当supported为null时显示"检查浏览器支持…",为false时显示提示信息,为true时显示翻译器。不需要订阅,因为页面打开期间浏览器支持不会改变,所以noopSubscribe不会执行任何操作。
### 不支持提示
没有相关API的浏览器会显示清晰的解释而不是破损的表单。创建components/unsupported-notice.tsx:
export function UnsupportedNotice() { return ( <div className="notice" role="alert"> <h2>此浏览器不支持 Chrome 内置的翻译功能</h2> <p> 翻译器和语言检测器 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。真正的 <label> 与 htmlFor 相关联,可以使控件更易访问并扩大点击区域:
import { AUTO, LANGUAGES } from "@/lib/languages";
interface Props { id: string; label: string; value: string; onChange: (code: string) => void; /** 添加 "检测语言" 选项(仅限源语言选择器)。 */ 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}>检测语言</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 API 是分开的,在大多数浏览器中都可以使用。 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={复制 ${label.toLowerCase()}}> {copied ? "✓" : "⧉"} </button> <button type="button" className="icon" onClick={speak} disabled={!value} aria-label={朗读 ${label.toLowerCase()}}> 🔊 </button> </div> </div> ); }
一些细节说明:
- 复制功能使用了剪贴板 API。
- 朗读功能使用了 Web Speech API 的 speechSynthesis 接口。这是一个与内置 AI API 完全不同的浏览器特性,且在大多数浏览器中都可用。我们通过设置 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() { // 服务端和水合阶段显示 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 会认为这是用户激活操作 // 这是下载模型前的必要条件 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="Swap languages" title="Swap languages" > ⇄ </button>
<div className="column"> <LanguageSelect id="target-language" label="To" value={target} onChange={setTarget} /> <TextPanel id="translation" label="Translation" value={output} lang={target} rtl={isRtl(target)} readOnly placeholder="The translation appears here." /> </div> </div>
<div className="submit-row"> {busy ? ( <button type="button" className="secondary" onClick={cancel}> Cancel </button> ) : ( <button type="submit" disabled={!text.trim()}> Translate </button> )} </div>
{downloadProgress !== null && ( <label className="progress"> Downloading language pack… {Math.round(downloadProgress * 100)}% <progress max={1} value={downloadProgress} /> </label> )}
{/* A live region announces status changes and errors to screen readers. */} <p role="status" aria-live="polite" className={error ? "status error" : "status"}> {statusMessage} </p> </form> </div>
一些细节值得注意。
表单的 onSubmit 处理程序会调用 translate()。由于它在提交表单的点击事件中运行,Chrome 会认为这是用户激活操作。这就是 Chrome 能够启动模型下载的原因。如果在页面加载时通过 useEffect 调用 Translator.create(),则不会有用户手势。
交换按钮会交换两种语言并将翻译内容移动到输入框中。如果源语言是“Detect language”,它会使用检测到的语言,并且在检测到语言之前会保持禁用状态。
状态行是一个 <p role="status" aria-live="polite">。屏幕阅读器会宣布“正在翻译…”、检测结果和错误等信息,而无需移动焦点。进度条有可见的标签。
### 页面和布局
最后,将其集成到应用中。app/page.tsx 是一个服务器组件,用于渲染客户端组件:
import { TranslatorApp } from "@/components/translator-app";
export default function Home() { return ( <main> <h1>使用 Chrome 内置 AI 进行翻译</h1> <p className="lede"> 文本由 Chrome 在您的设备上检测和翻译,不会发送到翻译服务器。 </p> <TranslatorApp /> </main> ); }
以及 app/layout.tsx:
import type { Metadata } from "next"; import "./globals.css";
export const metadata: Metadata = {
description: "一个使用 Chrome 翻译器和语言检测器 API 在设备上翻译文本的 Next.js 应用。", };
export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( <html lang="en"> <body>{children}</body> </html> ); }
我不会在这里重复 CSS,因为其中没有特定于 API 的内容。从仓库中复制 app/globals.css 文件。它为双列布局、按钮和进度条进行样式设计,并在小屏幕上折叠为单列。
## 如何运行和测试应用
启动开发服务器并在桌面 Chrome 中打开 URL:
npm run dev
然后尝试以下场景。这是我在 macOS 上 Chrome 156 中看到的结果:
| 我的操作 | 发生的情况 |
|---------|-----------|
| 输入 "This is a test sentence." 并将源语言设置为<br>检测语言<br>目标语言设置为<br>西班牙语 | 检测到 "英语(100% 确定性)" 并翻译为 "Esta es una oración de prueba." |
| 选择之前未使用过的语言对(英语到法语) | 下载语言包时进度条开始计数,我的网络连接下耗时约 15 秒,之后翻译结果出现 |
| 将西班牙语句子翻译成英语 | 检测到 "西班牙语(100% 确定性)" 并返回 "Hello, how are you today? I hope everything goes well." |
| 输入豪萨语句子 | Chrome 的检测器识别出它(`ha`),但翻译器报告无法从<br>豪萨语<br>翻译成英语 |
豪萨语的结果是一个很好的教训。语言检测和语言翻译支持的语言集是不同的。Chrome 的翻译器列表不包含豪萨语、约鲁巴语或伊博语,因此对于这些语言需要采用其他方法,例如服务器端模型或云翻译 API。
还可以尝试以下边缘情况:
- 在语言包下载过程中点击取消
- 选择检测语言时输入单个单词。短文本的检测可靠性较低,系统可能会提示您自行选择语言
- 为源语言和目标语言选择相同语言
如果在全新的 Chrome 用户配置文件中首次尝试时收到 "无法准备翻译" 的提示,请稍等片刻后重试。我在首次使用全新配置文件时,Chrome 在成功之前抛出了 NotSupportedError,这就是为什么 describeError 会解释这个错误而不是归咎于语言本身。
## 限制和生产环境考虑
内置的 AI API 使翻译代码保持简洁,但它们也伴随着需要规划的限制。
### 浏览器兼容性
这些功能目前仅限于桌面版 Chrome(和 Edge)。请将其视为渐进增强功能:
- 在使用前请像之前那样通过 "Translator" 特征检测进行检测
- 为其他用户提供回退方案(例如云翻译 API),并告知用户文本何时会离开设备
- 不要将产品其他功能隐藏在该特性之后
### 隐私
要明确 "私密" 的定义:
- 翻译和检测在本地运行。文本不会发送到翻译 API
- 模型下载仍然会发生。Chrome 会在首次使用语言对时通过网络下载语言包
- 确保自己的分析和错误日志系统绝不会捕获用户翻译的文本
### 质量和诚实性
- 语言检测是概率性的。请显示置信度,设置阈值,并允许用户覆盖检测结果
- Chrome 文档警告称检测器无法完全准确识别所有语言
- 不要仅依赖机器翻译处理法律、医疗、金融或其他高风险内容,对您支持的语言应由母语者审核输出结果
### 性能和资源
(此处原文段落不完整,未提供具体内容)
- 对长输入进行分块处理。翻译是按顺序进行的,因此长文本会延迟其后的内容。显示加载状态并拆分大型文档。
- 检查配额。某些实现会限制输入大小。翻译器会暴露 inputQuota 和 measureInputUsage(),因此在翻译前可以检查(这是 MDN 的模式,但尚未在此演示中实现):
const translator = await getTranslator("en", "es"); const usage = await translator.measureInputUsage(text); if (usage > translator.inputQuota) { throw new Error("该文本太长,无法一次性翻译。"); }
- 释放资源。对不再需要的翻译器调用 destroy(),就像 destroyAll() 一样。
### 嵌入和工作线程
- 这些 API 在 Web Workers 中不可用,因此你无法像使用 Transformers.js 这样的库那样将它们移出主线程。
- 跨域 iframe 需要具有 Permissions Policy allow 属性才能使用它们。
## 结论
你构建了一个基于 Next.js 的翻译器,它在设备上运行,无需模型托管或推理后端。在此过程中,你使用了 Translator 和 Language Detector API 的主要部分:功能检测、availability()、带有下载进度的 create()、带有置信度评分的 detect()、translateStreaming()、使用 AbortController 的取消操作以及 destroy()。
你还处理了在服务器渲染框架中使用基于浏览器的 AI 引入的问题:服务器上没有翻译器,模型按需下载并需要用户手势,支持仅限于某些浏览器,且质量因语言而异。
基于浏览器的 AI 并不会取代服务器端的 AI。它为你提供了另一种选择,可以降低成本和延迟,并将临时用户文本保留在设备上。在 Chrome 支持的情况下,你现在有了一个小型、基于标准的方式来构建多语言体验。
合作伙伴推荐课程(侧边栏,1/7)
(在新标签页中打开)
广告
- Udemy NodeJS 教程和项目课程 Yanis Smilga 4.6(4,185 条评分) 2天10小时58分钟 初学者 证书 查看课程(在新标签页中打开)
- Udemy NodeJS - 完整指南(MVC、REST APIs、GraphQL、Deno)Academind by Maximilian Schwarzmüller 4.6(55,454 条评分) 1天16小时32分钟 初学者 证书 查看课程(在新标签页中打开)
- Udemy 完整 Node.js 开发者课程(第三版)Andrew Mead 和 Rob Percival 4.6(74,004 条评分) 1天11小时3分钟 初学者 证书 查看课程(在新标签页中打开)
- Udemy 成为 Node.js 开发者:Node.js/Express.js/MongoDB/API Bluelime Learning Solutions 3.9(289 条评分) 9小时47分钟 初学者 证书 查看课程(在新标签页中打开)
更多 Node.js 课程在 Class Central
→
合作伙伴推荐课程(侧边栏,2/7)
- Udemy 通过构建 12 个项目学习 Nodejs Eduonix Learning Solutions 和 Eduonix-Tech 4.2(2,010 条评分) 12小时38分钟 初学者 证书 查看课程(在新标签页中打开)
- Udemy Node.js、Express、MongoDB 及更多:完整入门课程 Jonas Schmedtmann 4.6(29,767 条评分) 1天18小时13分钟 初学者 证书 查看课程(在新标签页中打开)
- 在 Udemy 上《Modern JavaScript From The Beginning 2.0(最新更新)》Brad Traversy 4.7(满分5分)(36,427人评价)1天16小时14分钟 初学者 可获得证书 查看课程(在新标签页中打开)
- 在 Coursera 上《Learn JavaScript》Per Harald Borgen 4.7(满分5分)(155人评价)8周,每周2小时 初学者 可获得证书 查看课程(在新标签页中打开)
合作伙伴推荐课程(侧边栏,3/7)
- 在 Coursera 上《Learn Node.js》Tom Chant 2周,每周1小时 中级 可获得证书 查看课程(在新标签页中打开)
- 在 Coursera 上《Developing Back-End Apps with Node.js and Express》Upkar Lidder 和 Sachin Jambur 4.5(满分5分)(631人评价)4周,每周3小时 中级 可获得证书 查看课程(在新标签页中打开)
合作伙伴推荐课程(侧边栏,4/7)
合作伙伴推荐课程(侧边栏,5/7)
合作伙伴推荐课程(侧边栏,6/7)
合作伙伴推荐课程(侧边栏,7/7)
专注于构建和维护可靠系统的软件工程师。
如果你读到这里,请感谢作者以表达你的支持。说声谢谢
免费学习编程。freeCodeCamp 的开源课程已帮助超过40,000人成为开发者。立即开始
合作伙伴推荐课程