1. 为什么我要自己动手做网页翻译插件浏览器自带的翻译功能说实话日常看个新闻、刷个外文博客勉强够用。但一旦遇到技术文档、学术论文、产品手册这类内容机翻的短板就暴露无遗——术语翻不准、代码块被搅乱、上下文断裂读起来比看原文还累。更别提有些页面结构复杂自带翻译直接把排版搞崩体验极差。我平时需要大量阅读英文技术资料DeepL 和 Google 翻译的效果确实好但免费额度有限用着用着就弹窗让你升级。商业翻译 API 按字符计费一个月下来也是一笔不小的开销。直到我开始接触大模型 API发现这事儿其实有更优雅的解法——用免费的大模型接口自己搭一个翻译插件成本几乎为零翻译质量还比传统机翻高出一大截。这个项目的核心思路很简单写一个浏览器扩展拦截网页内容调用大模型 API 进行翻译再把译文替换回页面。技术栈就是Node.js做构建工具OpenAI 兼容接口做翻译引擎浏览器扩展 API 做页面注入。整套方案不需要服务器不需要数据库一个浏览器插件加上一个 API Key 就能跑起来。适合谁来参考如果你有基础的前端知识懂一点 JavaScript想拥有一个完全可控、免费、翻译质量又好的网页翻译工具那这篇内容就是为你准备的。哪怕你之前没写过浏览器扩展跟着思路走也能搭出来。我会把踩过的坑、参数怎么调、API 怎么选这些细节都讲清楚。2. 整体方案设计与技术选型拆解2.1 为什么选浏览器扩展而不是油猴脚本做网页翻译最轻量的方案其实是油猴脚本UserScript。写几十行 JavaScript注入到页面里调用翻译 API替换文本节点完事。但油猴脚本有几个硬伤一是权限管理粗放所有网站都能跑容易和页面原有脚本冲突二是没有独立的 UI 空间想做个翻译开关、语言选择、进度提示只能往页面里塞 DOM样式容易被覆盖三是跨域请求受限虽然油猴有 GM_xmlhttpRequest 可以绕过但配置起来麻烦。浏览器扩展Chrome Extension / Edge Add-on就不一样了。它有独立的 content script 运行环境有 background service worker 处理网络请求有 popup 页面做交互界面还有 storage API 存配置。权限可以精确控制到具体域名不会干扰无关页面。更重要的是扩展的代码结构清晰方便后续维护和功能扩展。我实测下来用扩展方案虽然初期搭建多花一两个小时但后期调试和迭代的效率高得多。2.2 大模型 API 的选择逻辑市面上的大模型 API 大致分几类OpenAI 官方、国内大厂智谱、百度、阿里等、开源模型托管平台、以及各种免费额度渠道。选哪个核心看三个维度翻译质量、调用成本、访问稳定性。OpenAI 的 GPT 系列翻译质量没得说但官方 API 需要海外支付方式而且按 token 计费长期用成本不低。国内大厂的 API 如智谱 GLM、DeepSeek 等翻译质量已经非常接近而且经常有免费额度活动注册就送几百万 token个人用完全够。开源模型托管平台如硅基流动、Together AI 等提供各种开源模型的 API部分模型免费适合折腾。我的建议是优先选国内大厂的免费额度。注册简单支付方便访问稳定翻译质量足够。具体选哪家看你手头有什么账号。智谱、DeepSeek、月之暗面Kimi都有 OpenAI 兼容接口意味着你只需要改一下 base_url 和 model 名称代码完全不用动。这就是为什么我坚持用 OpenAI 兼容格式——换供应商的成本几乎为零。注意不要直接把 API Key 硬编码在扩展代码里。浏览器扩展的代码是可以被用户查看的Key 泄露了别人就能盗用你的额度。正确做法是把 Key 存在扩展的 storage 里通过设置页面让用户自己填。2.3 翻译策略整页翻译还是划词翻译网页翻译有两种常见模式整页翻译和划词翻译。整页翻译是把页面上所有可见文本提取出来批量发给大模型拿到译文后替换回去。划词翻译是用户选中一段文字弹出翻译结果。整页翻译的难点在于文本节点提取和还原。网页的 DOM 结构很复杂文本散落在各种标签里还有嵌套、隐藏元素、动态加载的内容。如果粗暴地遍历所有文本节点会把代码块、公式、URL 也翻掉导致页面功能异常。我的做法是只提取可见的、非代码区域的文本节点用 TreeWalker 遍历过滤掉script、style、code、pre等标签内的内容。翻译完成后按节点顺序替换回去保持原有 DOM 结构不变。划词翻译相对简单但体验上不如整页翻译流畅。我的方案是两者都做默认整页翻译用户选中文字时弹出划词翻译浮层。这样既满足快速浏览的需求也方便精读时查词。2.4 技术栈与项目结构整个项目用Node.js做构建工具主要是为了用打包器如 esbuild 或 webpack把多个 JS 文件合并成一个 content script同时处理依赖和压缩。Node.js 版本建议用 LTS 20 以上安装过程不复杂官网下载安装包一路下一步就行。如果你在 Ubuntu 上用nvm装 Node.js 会更方便管理版本。项目结构大致如下translator-extension/ ├── manifest.json # 扩展配置文件 ├── src/ │ ├── background.js # 后台服务处理 API 请求 │ ├── content.js # 内容脚本注入页面 │ ├── popup.html # 弹窗界面 │ ├── popup.js # 弹窗逻辑 │ └── options.html # 设置页面 ├── package.json └── build.js # 构建脚本manifest.json是扩展的入口声明权限、后台脚本、内容脚本、弹窗页面等。Chrome 扩展目前推荐用 Manifest V3后台脚本用 service worker 代替原来的 background page。这个变化影响不大主要是生命周期管理要注意——service worker 会休眠不能在里面存全局状态所有配置都放chrome.storage。3. 核心细节解析与实操要点3.1 文本节点提取的过滤规则整页翻译最关键的一步是提取文本节点。我试过几种方案最后定下来的过滤规则是这样的跳过script、style、noscript、code、pre、kbd、samp标签内的文本跳过contenteditabletrue的元素避免翻译输入框内容跳过display: none或visibility: hidden的元素跳过纯数字、纯符号、URL、邮箱地址等不需要翻译的内容跳过长度小于 2 的文本节点减少无效请求用 TreeWalker 遍历时可以设置NodeFilter.SHOW_TEXT然后在 filter 函数里做上述判断。这里有个细节不要直接修改 DOM而是先把所有符合条件的文本节点收集到一个数组里记录每个节点的原始文本和父节点引用。翻译完成后再统一替换避免遍历过程中 DOM 变化导致漏掉节点。function collectTextNodes(root) { const walker document.createTreeWalker( root, NodeFilter.SHOW_TEXT, { acceptNode(node) { const parent node.parentElement; if (!parent) return NodeFilter.FILTER_REJECT; const tag parent.tagName.toLowerCase(); if ([script, style, noscript, code, pre].includes(tag)) { return NodeFilter.FILTER_REJECT; } if (parent.isContentEditable) return NodeFilter.FILTER_REJECT; const text node.textContent.trim(); if (text.length 2) return NodeFilter.FILTER_REJECT; if (/^[\d\s\p{P}]$/u.test(text)) return NodeFilter.FILTER_REJECT; return NodeFilter.FILTER_ACCEPT; } } ); const nodes []; while (walker.nextNode()) { nodes.push(walker.currentNode); } return nodes; }3.2 批量翻译的请求合并与分片大模型 API 有上下文长度限制虽然现在很多模型支持 128K 甚至更长的上下文但一次性把整页文本发过去还是不现实。一是 token 消耗大二是响应时间长三是容易触发限流。我的做法是分片批量翻译把收集到的文本节点按一定规则分组每组不超过 2000 个字符然后逐组发送请求。分组时要注意不要把同一个段落拆到两个组里。虽然大模型能理解上下文但拆开翻译会导致语义断裂。我的策略是按 DOM 顺序累加文本长度超过阈值就切分同时尽量在段落边界处切分。具体实现时可以给每个文本节点打上段落标记同一段落内的节点尽量分到同一组。请求合并还有一个好处减少 API 调用次数。每次请求都有网络开销和固定 token 消耗系统提示词合并后能显著降低成本。我实测下来一个中等长度的技术文档页面分片后大概 5-8 个请求就能翻完耗时 10-20 秒完全可以接受。3.3 翻译提示词的设计技巧大模型翻译的质量很大程度上取决于提示词。我试过很多版本最后定下来的提示词是这样的你是一个专业的网页翻译引擎。请将以下文本翻译成中文要求 1. 保持原文的格式和换行 2. 技术术语保留英文原文并在括号内给出中文翻译 3. 代码、变量名、URL 不翻译 4. 只输出译文不要添加任何解释 5. 如果文本已经是中文原样返回 待翻译文本 {text}这个提示词的关键点在于明确输出格式、保留技术术语、禁止添加解释。很多大模型默认会加一句“以下是翻译结果”或者对术语进行过度翻译导致译文不可用。通过提示词约束可以大幅提升翻译的可用性。另外温度参数temperature要调低。翻译任务不需要创造性温度设为 0.1-0.3 即可保证输出稳定。max_tokens要设得足够大避免译文被截断。一般按输入文本长度的 2-3 倍估算比如输入 1000 字符max_tokens设 2000-3000。3.4 译文替换与页面重排拿到译文后替换回原文本节点。这里有个坑大模型返回的译文可能和原文的节点数量不一致。比如原文有 5 个文本节点模型返回的译文可能合并成 3 段或者多出一些换行。如果直接按顺序替换会导致文本错位。我的解决方案是给每个文本节点加唯一标识。在发送请求时把文本节点编号格式化成[1] 文本内容\n[2] 文本内容...要求模型按编号返回译文。解析响应时按编号匹配回对应的节点。这样即使模型合并或拆分段落也能准确还原。// 发送时格式化 const payload nodes.map((node, i) [${i}] ${node.textContent}).join(\n); // 解析响应 const lines response.split(\n); lines.forEach(line { const match line.match(/^\[(\d)\]\s*(.)/); if (match) { const index parseInt(match[1]); const translated match[2]; if (nodes[index]) { nodes[index].textContent translated; } } });替换完成后页面可能会因为文本长度变化导致布局错乱。这时候可以触发一次window.dispatchEvent(new Event(resize))让页面重新计算布局。大部分网站能自动适应少数固定宽度的元素可能需要额外处理但这种情况很少见。4. 实操过程与核心环节实现4.1 环境准备与项目初始化先装 Node.js。Windows 和 macOS 直接去官网下载 LTS 版本一路下一步。Ubuntu 用户建议用 nvm 安装命令如下curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20装完后验证一下node -v和npm -v能输出版本号就行。然后创建项目目录初始化 package.jsonmkdir translator-extension cd translator-extension npm init -y npm install esbuild --save-devesbuild 是我常用的打包工具速度快配置简单。在package.json里加一个构建脚本{ scripts: { build: node build.js, watch: node build.js --watch } }build.js的内容很简单就是调用 esbuild 把src/content.js和src/background.js分别打包const esbuild require(esbuild); const watch process.argv.includes(--watch); const config { entryPoints: [src/content.js, src/background.js], bundle: true, outdir: dist, format: iife, target: chrome100, minify: !watch, }; if (watch) { esbuild.context(config).then(ctx ctx.watch()); } else { esbuild.build(config); }4.2 manifest.json 配置详解Manifest V3 的配置和 V2 有不少区别这里直接给出一份可用的配置{ manifest_version: 3, name: AI 网页翻译, version: 1.0.0, description: 用大模型 API 翻译网页内容, permissions: [storage, activeTab, scripting], host_permissions: [all_urls], background: { service_worker: dist/background.js }, content_scripts: [ { matches: [all_urls], js: [dist/content.js], run_at: document_idle } ], action: { default_popup: src/popup.html, default_title: AI 翻译 }, options_page: src/options.html }几个关键点permissions里storage用于存配置activeTab和scripting用于动态注入脚本。host_permissions设为all_urls是为了让扩展能在所有网站上运行如果你只想在特定网站用可以改成具体的域名。run_at设为document_idle等页面基本加载完再注入避免干扰页面初始化。4.3 后台服务与 API 调用封装background.js 负责处理 API 请求。因为 content script 直接发跨域请求会受 CORS 限制所以统一由 background 代理。Manifest V3 的 service worker 支持fetch但要注意它会在空闲时休眠所以每次请求都要从 storage 读取配置不能依赖全局变量。async function translate(text, config) { const { apiKey, baseUrl, model } config; const response await fetch(${baseUrl}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: model, messages: [ { role: system, content: 你是一个专业的网页翻译引擎... }, { role: user, content: text } ], temperature: 0.2, max_tokens: 4000 }) }); if (!response.ok) { const error await response.text(); throw new Error(API 请求失败: ${response.status} ${error}); } const data await response.json(); return data.choices[0].message.content; }content script 通过chrome.runtime.sendMessage和 background 通信chrome.runtime.sendMessage( { type: translate, text: payload }, (response) { if (response.error) { console.error(翻译失败:, response.error); return; } // 处理译文 } );4.4 设置页面与配置存储设置页面让用户填 API Key、选择服务商、调整翻译参数。用chrome.storage.sync存储这样换设备登录同一账号也能同步配置。页面结构很简单几个输入框加一个保存按钮labelAPI Key/label input typepassword idapiKey placeholdersk-... labelAPI 地址/label input typetext idbaseUrl valuehttps://open.bigmodel.cn/api/paas/v4 label模型名称/label input typetext idmodel valueglm-4-flash button idsave保存/button保存逻辑document.getElementById(save).addEventListener(click, () { const config { apiKey: document.getElementById(apiKey).value.trim(), baseUrl: document.getElementById(baseUrl).value.trim(), model: document.getElementById(model).value.trim() }; chrome.storage.sync.set(config, () { alert(配置已保存); }); });提示不同服务商的 baseUrl 和 model 名称不一样。智谱的 baseUrl 是https://open.bigmodel.cn/api/paas/v4模型填glm-4-flash免费。DeepSeek 的 baseUrl 是https://api.deepseek.com/v1模型填deepseek-chat。Kimi 的 baseUrl 是https://api.moonshot.cn/v1模型填moonshot-v1-8k。具体以各家文档为准。4.5 翻译触发与进度反馈翻译触发方式我做了三种点击扩展图标弹出 popup 后点“翻译本页”、快捷键CtrlShiftT、以及右键菜单。popup 里显示翻译进度比如“正在翻译 3/8 段”。进度反馈很重要因为整页翻译需要几秒到几十秒没有反馈用户会以为卡死了。进度更新通过chrome.runtime.sendMessage从 content script 发到 popupchrome.runtime.sendMessage({ type: progress, current: i 1, total: chunks.length });popup 里监听消息并更新 UIchrome.runtime.onMessage.addListener((message) { if (message.type progress) { document.getElementById(status).textContent 正在翻译 ${message.current}/${message.total} 段; } });5. 常见问题与排查技巧实录5.1 API 请求失败排查表错误现象可能原因解决方法401 UnauthorizedAPI Key 错误或过期检查 Key 是否复制完整重新生成403 Forbidden权限不足或余额耗尽检查账户余额确认模型权限429 Too Many Requests请求频率超限降低并发数增加请求间隔400 Bad Request参数格式错误检查 model 名称、max_tokens 设置超时无响应网络问题或服务商故障切换服务商检查网络连接返回内容为空提示词被拦截或模型异常调整提示词换模型测试5.2 翻译质量不稳定的调优经验大模型翻译偶尔会“抽风”比如把整段话翻成英文、添加莫名其妙的解释、或者直接返回原文。我总结了几条调优经验第一温度参数别设太高。0.1-0.3 之间最稳超过 0.5 就开始出现创造性翻译对翻译任务来说是灾难。第二提示词里加 few-shot 示例。给一两个输入输出示例模型会模仿格式稳定性明显提升。比如示例输入[1] Hello world 示例输出[1] 你好世界第三分片不要太大。单次请求文本控制在 2000 字符以内超过后模型容易漏翻或合并段落。虽然多几次请求但质量更可控。第四遇到异常结果做重试。如果某段译文明显不对比如长度只有原文的十分之一或者全是英文自动重试一次。重试时把温度再调低通常能拿到正常结果。5.3 页面兼容性问题的处理不同网站的 DOM 结构差异很大有些页面翻译后会出问题。我遇到过的典型情况单页应用SPA动态加载内容。比如 React、Vue 写的网站页面内容是通过 JS 动态渲染的。翻译时如果只抓取初始 DOM会漏掉后续加载的内容。解决方案是用MutationObserver监听 DOM 变化有新文本节点时自动翻译。但要注意防抖避免频繁触发。iframe 嵌套页面。有些网站把内容放在 iframe 里content script 默认只注入顶层页面。需要在 manifest 里加all_frames: true让脚本注入所有 frame。但跨域 iframe 仍然无法访问这是浏览器安全限制无解。代码高亮插件干扰。有些技术博客用 Prism.js 或 Highlight.js 做代码高亮这些插件会把代码拆成很多 span 标签。我的过滤规则里已经跳过了code和pre但如果代码没有用这些标签包裹就可能被误翻。这种情况只能靠用户手动排除或者在设置里加一个“跳过选择器”的配置项。5.4 性能优化的几个实用技巧整页翻译的性能瓶颈主要在 API 请求上。除了分片合并还有几个优化点并发控制。不要一次性把所有分片都发出去容易触发限流。我设的是最多 3 个并发用 Promise 池控制。实测下来3 并发比串行快一倍多又不会触发 429。缓存译文。同一段文本如果之前翻译过直接读缓存不用再请求 API。用Map在内存里存页面刷新后失效。如果想持久化可以存到chrome.storage.local但要注意容量限制。懒翻译。只翻译视口内的内容滚动到哪翻到哪。这个方案对长页面很友好但实现复杂度高需要监听滚动事件、计算元素位置。我目前没做因为分片批量翻译已经够快了。跳过已翻译内容。给翻译过的节点加一个>document.addEventListener(mouseup, async (e) { const selection window.getSelection(); const text selection.toString().trim(); if (!text || text.length 2) return; const range selection.getRangeAt(0); const rect range.getBoundingClientRect(); // 显示浮层 const popup document.createElement(div); popup.className ai-translate-popup; popup.style.left ${rect.left}px; popup.style.top ${rect.bottom 8}px; popup.textContent 翻译中...; document.body.appendChild(popup); // 请求翻译 const result await translateText(text); popup.textContent result; });浮层的样式要用z-index: 2147483647确保在最上层同时加box-shadow和圆角视觉上更舒服。点击页面其他位置时移除浮层。6.2 多语言支持与自动检测默认翻译成中文但有时候需要翻译成其他语言。可以在设置里加一个目标语言选项支持英语、日语、韩语、法语、德语等。提示词里把“翻译成中文”改成动态变量即可。源语言检测可以交给大模型做在提示词里加一句“自动检测源语言”。但这样会增加 token 消耗。更经济的做法是用简单的字符集判断如果文本中中文字符占比超过 30%认为是中文跳过翻译如果包含西里尔字母可能是俄语包含阿拉伯字母可能是阿拉伯语。粗略判断足够用准确率交给大模型兜底。6.3 翻译历史与生词本每次翻译的结果可以存到chrome.storage.local形成一个翻译历史。用户可以在 popup 里查看最近翻译的段落方便回顾。如果加上生词本功能把划词翻译的单词和释义存下来就变成了一个简易的语言学习工具。存储结构设计{ history: [ { source: Hello world, target: 你好世界, time: 1700000000000 }, // ... ], vocabulary: [ { word: hello, meaning: 你好, context: Hello world, time: 1700000000000 } ] }历史记录限制最多 500 条超出后删除最旧的。生词本不限制但提供导出功能可以导出成 CSV 或 Anki 格式。6.4 自定义提示词模板高级用户可能想自己调提示词。可以在设置页面加一个文本框让用户自定义系统提示词。默认填入我调好的模板用户修改后保存。这样既照顾了小白也给折腾党留了空间。提示词模板里可以用的变量{targetLang}目标语言、{sourceLang}源语言可选。替换后再发给 API。const systemPrompt template .replace({targetLang}, config.targetLang || 中文) .replace({sourceLang}, config.sourceLang || 自动检测);7. 我踩过的坑与最终建议这个项目我从零开始搭前后迭代了十几个版本踩的坑不少。最大的一个坑是Manifest V3 的 service worker 休眠问题。一开始我把 API 配置存在 background 的全局变量里结果 service worker 休眠后变量丢失翻译请求全部失败。排查了半天才意识到是生命周期问题改成每次从chrome.storage读取后就好了。第二个坑是文本节点替换后的布局错乱。有些网站用text-overflow: ellipsis做截断翻译后文本变长省略号位置不对。解决方案是翻译后给元素加一个title属性把完整译文放进去鼠标悬停能看到全文。第三个坑是API 限流。免费额度的 API 通常有 QPS 限制并发一高就 429。我的做法是加一个简单的令牌桶限流器控制请求速率。具体实现就是维护一个时间戳队列每次请求前检查最近一秒内的请求数超过阈值就await sleep。如果你打算动手做我的建议是先跑通最小可用版本再逐步加功能。不要一上来就追求完美先把“提取文本-调用 API-替换译文”这个核心链路跑通哪怕只支持一个网站、只翻译一段文字。跑通之后再考虑分片、并发、缓存、划词这些进阶功能。这样每一步都有正反馈不容易半途而废。API 服务商的选择上我目前主力用智谱的 GLM-4-Flash免费额度大翻译质量稳定响应速度也快。DeepSeek 作为备用偶尔对比一下效果。两家都是 OpenAI 兼容接口切换成本几乎为零。如果你手头有其他的免费额度渠道改一下 baseUrl 和 model 就能用代码完全不用动。最后再分享一个小技巧翻译前先备份原始文本。在替换节点之前把原始文本存到节点的>
1. 为什么我要自己动手做网页翻译插件浏览器自带的翻译功能说实话日常看个新闻、刷个外文博客勉强够用。但一旦遇到技术文档、学术论文、产品手册这类内容机翻的短板就暴露无遗——术语翻不准、代码块被搅乱、上下文断裂读起来比看原文还累。更别提有些页面结构复杂自带翻译直接把排版搞崩体验极差。我平时需要大量阅读英文技术资料DeepL 和 Google 翻译的效果确实好但免费额度有限用着用着就弹窗让你升级。商业翻译 API 按字符计费一个月下来也是一笔不小的开销。直到我开始接触大模型 API发现这事儿其实有更优雅的解法——用免费的大模型接口自己搭一个翻译插件成本几乎为零翻译质量还比传统机翻高出一大截。这个项目的核心思路很简单写一个浏览器扩展拦截网页内容调用大模型 API 进行翻译再把译文替换回页面。技术栈就是Node.js做构建工具OpenAI 兼容接口做翻译引擎浏览器扩展 API 做页面注入。整套方案不需要服务器不需要数据库一个浏览器插件加上一个 API Key 就能跑起来。适合谁来参考如果你有基础的前端知识懂一点 JavaScript想拥有一个完全可控、免费、翻译质量又好的网页翻译工具那这篇内容就是为你准备的。哪怕你之前没写过浏览器扩展跟着思路走也能搭出来。我会把踩过的坑、参数怎么调、API 怎么选这些细节都讲清楚。2. 整体方案设计与技术选型拆解2.1 为什么选浏览器扩展而不是油猴脚本做网页翻译最轻量的方案其实是油猴脚本UserScript。写几十行 JavaScript注入到页面里调用翻译 API替换文本节点完事。但油猴脚本有几个硬伤一是权限管理粗放所有网站都能跑容易和页面原有脚本冲突二是没有独立的 UI 空间想做个翻译开关、语言选择、进度提示只能往页面里塞 DOM样式容易被覆盖三是跨域请求受限虽然油猴有 GM_xmlhttpRequest 可以绕过但配置起来麻烦。浏览器扩展Chrome Extension / Edge Add-on就不一样了。它有独立的 content script 运行环境有 background service worker 处理网络请求有 popup 页面做交互界面还有 storage API 存配置。权限可以精确控制到具体域名不会干扰无关页面。更重要的是扩展的代码结构清晰方便后续维护和功能扩展。我实测下来用扩展方案虽然初期搭建多花一两个小时但后期调试和迭代的效率高得多。2.2 大模型 API 的选择逻辑市面上的大模型 API 大致分几类OpenAI 官方、国内大厂智谱、百度、阿里等、开源模型托管平台、以及各种免费额度渠道。选哪个核心看三个维度翻译质量、调用成本、访问稳定性。OpenAI 的 GPT 系列翻译质量没得说但官方 API 需要海外支付方式而且按 token 计费长期用成本不低。国内大厂的 API 如智谱 GLM、DeepSeek 等翻译质量已经非常接近而且经常有免费额度活动注册就送几百万 token个人用完全够。开源模型托管平台如硅基流动、Together AI 等提供各种开源模型的 API部分模型免费适合折腾。我的建议是优先选国内大厂的免费额度。注册简单支付方便访问稳定翻译质量足够。具体选哪家看你手头有什么账号。智谱、DeepSeek、月之暗面Kimi都有 OpenAI 兼容接口意味着你只需要改一下 base_url 和 model 名称代码完全不用动。这就是为什么我坚持用 OpenAI 兼容格式——换供应商的成本几乎为零。注意不要直接把 API Key 硬编码在扩展代码里。浏览器扩展的代码是可以被用户查看的Key 泄露了别人就能盗用你的额度。正确做法是把 Key 存在扩展的 storage 里通过设置页面让用户自己填。2.3 翻译策略整页翻译还是划词翻译网页翻译有两种常见模式整页翻译和划词翻译。整页翻译是把页面上所有可见文本提取出来批量发给大模型拿到译文后替换回去。划词翻译是用户选中一段文字弹出翻译结果。整页翻译的难点在于文本节点提取和还原。网页的 DOM 结构很复杂文本散落在各种标签里还有嵌套、隐藏元素、动态加载的内容。如果粗暴地遍历所有文本节点会把代码块、公式、URL 也翻掉导致页面功能异常。我的做法是只提取可见的、非代码区域的文本节点用 TreeWalker 遍历过滤掉script、style、code、pre等标签内的内容。翻译完成后按节点顺序替换回去保持原有 DOM 结构不变。划词翻译相对简单但体验上不如整页翻译流畅。我的方案是两者都做默认整页翻译用户选中文字时弹出划词翻译浮层。这样既满足快速浏览的需求也方便精读时查词。2.4 技术栈与项目结构整个项目用Node.js做构建工具主要是为了用打包器如 esbuild 或 webpack把多个 JS 文件合并成一个 content script同时处理依赖和压缩。Node.js 版本建议用 LTS 20 以上安装过程不复杂官网下载安装包一路下一步就行。如果你在 Ubuntu 上用nvm装 Node.js 会更方便管理版本。项目结构大致如下translator-extension/ ├── manifest.json # 扩展配置文件 ├── src/ │ ├── background.js # 后台服务处理 API 请求 │ ├── content.js # 内容脚本注入页面 │ ├── popup.html # 弹窗界面 │ ├── popup.js # 弹窗逻辑 │ └── options.html # 设置页面 ├── package.json └── build.js # 构建脚本manifest.json是扩展的入口声明权限、后台脚本、内容脚本、弹窗页面等。Chrome 扩展目前推荐用 Manifest V3后台脚本用 service worker 代替原来的 background page。这个变化影响不大主要是生命周期管理要注意——service worker 会休眠不能在里面存全局状态所有配置都放chrome.storage。3. 核心细节解析与实操要点3.1 文本节点提取的过滤规则整页翻译最关键的一步是提取文本节点。我试过几种方案最后定下来的过滤规则是这样的跳过script、style、noscript、code、pre、kbd、samp标签内的文本跳过contenteditabletrue的元素避免翻译输入框内容跳过display: none或visibility: hidden的元素跳过纯数字、纯符号、URL、邮箱地址等不需要翻译的内容跳过长度小于 2 的文本节点减少无效请求用 TreeWalker 遍历时可以设置NodeFilter.SHOW_TEXT然后在 filter 函数里做上述判断。这里有个细节不要直接修改 DOM而是先把所有符合条件的文本节点收集到一个数组里记录每个节点的原始文本和父节点引用。翻译完成后再统一替换避免遍历过程中 DOM 变化导致漏掉节点。function collectTextNodes(root) { const walker document.createTreeWalker( root, NodeFilter.SHOW_TEXT, { acceptNode(node) { const parent node.parentElement; if (!parent) return NodeFilter.FILTER_REJECT; const tag parent.tagName.toLowerCase(); if ([script, style, noscript, code, pre].includes(tag)) { return NodeFilter.FILTER_REJECT; } if (parent.isContentEditable) return NodeFilter.FILTER_REJECT; const text node.textContent.trim(); if (text.length 2) return NodeFilter.FILTER_REJECT; if (/^[\d\s\p{P}]$/u.test(text)) return NodeFilter.FILTER_REJECT; return NodeFilter.FILTER_ACCEPT; } } ); const nodes []; while (walker.nextNode()) { nodes.push(walker.currentNode); } return nodes; }3.2 批量翻译的请求合并与分片大模型 API 有上下文长度限制虽然现在很多模型支持 128K 甚至更长的上下文但一次性把整页文本发过去还是不现实。一是 token 消耗大二是响应时间长三是容易触发限流。我的做法是分片批量翻译把收集到的文本节点按一定规则分组每组不超过 2000 个字符然后逐组发送请求。分组时要注意不要把同一个段落拆到两个组里。虽然大模型能理解上下文但拆开翻译会导致语义断裂。我的策略是按 DOM 顺序累加文本长度超过阈值就切分同时尽量在段落边界处切分。具体实现时可以给每个文本节点打上段落标记同一段落内的节点尽量分到同一组。请求合并还有一个好处减少 API 调用次数。每次请求都有网络开销和固定 token 消耗系统提示词合并后能显著降低成本。我实测下来一个中等长度的技术文档页面分片后大概 5-8 个请求就能翻完耗时 10-20 秒完全可以接受。3.3 翻译提示词的设计技巧大模型翻译的质量很大程度上取决于提示词。我试过很多版本最后定下来的提示词是这样的你是一个专业的网页翻译引擎。请将以下文本翻译成中文要求 1. 保持原文的格式和换行 2. 技术术语保留英文原文并在括号内给出中文翻译 3. 代码、变量名、URL 不翻译 4. 只输出译文不要添加任何解释 5. 如果文本已经是中文原样返回 待翻译文本 {text}这个提示词的关键点在于明确输出格式、保留技术术语、禁止添加解释。很多大模型默认会加一句“以下是翻译结果”或者对术语进行过度翻译导致译文不可用。通过提示词约束可以大幅提升翻译的可用性。另外温度参数temperature要调低。翻译任务不需要创造性温度设为 0.1-0.3 即可保证输出稳定。max_tokens要设得足够大避免译文被截断。一般按输入文本长度的 2-3 倍估算比如输入 1000 字符max_tokens设 2000-3000。3.4 译文替换与页面重排拿到译文后替换回原文本节点。这里有个坑大模型返回的译文可能和原文的节点数量不一致。比如原文有 5 个文本节点模型返回的译文可能合并成 3 段或者多出一些换行。如果直接按顺序替换会导致文本错位。我的解决方案是给每个文本节点加唯一标识。在发送请求时把文本节点编号格式化成[1] 文本内容\n[2] 文本内容...要求模型按编号返回译文。解析响应时按编号匹配回对应的节点。这样即使模型合并或拆分段落也能准确还原。// 发送时格式化 const payload nodes.map((node, i) [${i}] ${node.textContent}).join(\n); // 解析响应 const lines response.split(\n); lines.forEach(line { const match line.match(/^\[(\d)\]\s*(.)/); if (match) { const index parseInt(match[1]); const translated match[2]; if (nodes[index]) { nodes[index].textContent translated; } } });替换完成后页面可能会因为文本长度变化导致布局错乱。这时候可以触发一次window.dispatchEvent(new Event(resize))让页面重新计算布局。大部分网站能自动适应少数固定宽度的元素可能需要额外处理但这种情况很少见。4. 实操过程与核心环节实现4.1 环境准备与项目初始化先装 Node.js。Windows 和 macOS 直接去官网下载 LTS 版本一路下一步。Ubuntu 用户建议用 nvm 安装命令如下curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20装完后验证一下node -v和npm -v能输出版本号就行。然后创建项目目录初始化 package.jsonmkdir translator-extension cd translator-extension npm init -y npm install esbuild --save-devesbuild 是我常用的打包工具速度快配置简单。在package.json里加一个构建脚本{ scripts: { build: node build.js, watch: node build.js --watch } }build.js的内容很简单就是调用 esbuild 把src/content.js和src/background.js分别打包const esbuild require(esbuild); const watch process.argv.includes(--watch); const config { entryPoints: [src/content.js, src/background.js], bundle: true, outdir: dist, format: iife, target: chrome100, minify: !watch, }; if (watch) { esbuild.context(config).then(ctx ctx.watch()); } else { esbuild.build(config); }4.2 manifest.json 配置详解Manifest V3 的配置和 V2 有不少区别这里直接给出一份可用的配置{ manifest_version: 3, name: AI 网页翻译, version: 1.0.0, description: 用大模型 API 翻译网页内容, permissions: [storage, activeTab, scripting], host_permissions: [all_urls], background: { service_worker: dist/background.js }, content_scripts: [ { matches: [all_urls], js: [dist/content.js], run_at: document_idle } ], action: { default_popup: src/popup.html, default_title: AI 翻译 }, options_page: src/options.html }几个关键点permissions里storage用于存配置activeTab和scripting用于动态注入脚本。host_permissions设为all_urls是为了让扩展能在所有网站上运行如果你只想在特定网站用可以改成具体的域名。run_at设为document_idle等页面基本加载完再注入避免干扰页面初始化。4.3 后台服务与 API 调用封装background.js 负责处理 API 请求。因为 content script 直接发跨域请求会受 CORS 限制所以统一由 background 代理。Manifest V3 的 service worker 支持fetch但要注意它会在空闲时休眠所以每次请求都要从 storage 读取配置不能依赖全局变量。async function translate(text, config) { const { apiKey, baseUrl, model } config; const response await fetch(${baseUrl}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: model, messages: [ { role: system, content: 你是一个专业的网页翻译引擎... }, { role: user, content: text } ], temperature: 0.2, max_tokens: 4000 }) }); if (!response.ok) { const error await response.text(); throw new Error(API 请求失败: ${response.status} ${error}); } const data await response.json(); return data.choices[0].message.content; }content script 通过chrome.runtime.sendMessage和 background 通信chrome.runtime.sendMessage( { type: translate, text: payload }, (response) { if (response.error) { console.error(翻译失败:, response.error); return; } // 处理译文 } );4.4 设置页面与配置存储设置页面让用户填 API Key、选择服务商、调整翻译参数。用chrome.storage.sync存储这样换设备登录同一账号也能同步配置。页面结构很简单几个输入框加一个保存按钮labelAPI Key/label input typepassword idapiKey placeholdersk-... labelAPI 地址/label input typetext idbaseUrl valuehttps://open.bigmodel.cn/api/paas/v4 label模型名称/label input typetext idmodel valueglm-4-flash button idsave保存/button保存逻辑document.getElementById(save).addEventListener(click, () { const config { apiKey: document.getElementById(apiKey).value.trim(), baseUrl: document.getElementById(baseUrl).value.trim(), model: document.getElementById(model).value.trim() }; chrome.storage.sync.set(config, () { alert(配置已保存); }); });提示不同服务商的 baseUrl 和 model 名称不一样。智谱的 baseUrl 是https://open.bigmodel.cn/api/paas/v4模型填glm-4-flash免费。DeepSeek 的 baseUrl 是https://api.deepseek.com/v1模型填deepseek-chat。Kimi 的 baseUrl 是https://api.moonshot.cn/v1模型填moonshot-v1-8k。具体以各家文档为准。4.5 翻译触发与进度反馈翻译触发方式我做了三种点击扩展图标弹出 popup 后点“翻译本页”、快捷键CtrlShiftT、以及右键菜单。popup 里显示翻译进度比如“正在翻译 3/8 段”。进度反馈很重要因为整页翻译需要几秒到几十秒没有反馈用户会以为卡死了。进度更新通过chrome.runtime.sendMessage从 content script 发到 popupchrome.runtime.sendMessage({ type: progress, current: i 1, total: chunks.length });popup 里监听消息并更新 UIchrome.runtime.onMessage.addListener((message) { if (message.type progress) { document.getElementById(status).textContent 正在翻译 ${message.current}/${message.total} 段; } });5. 常见问题与排查技巧实录5.1 API 请求失败排查表错误现象可能原因解决方法401 UnauthorizedAPI Key 错误或过期检查 Key 是否复制完整重新生成403 Forbidden权限不足或余额耗尽检查账户余额确认模型权限429 Too Many Requests请求频率超限降低并发数增加请求间隔400 Bad Request参数格式错误检查 model 名称、max_tokens 设置超时无响应网络问题或服务商故障切换服务商检查网络连接返回内容为空提示词被拦截或模型异常调整提示词换模型测试5.2 翻译质量不稳定的调优经验大模型翻译偶尔会“抽风”比如把整段话翻成英文、添加莫名其妙的解释、或者直接返回原文。我总结了几条调优经验第一温度参数别设太高。0.1-0.3 之间最稳超过 0.5 就开始出现创造性翻译对翻译任务来说是灾难。第二提示词里加 few-shot 示例。给一两个输入输出示例模型会模仿格式稳定性明显提升。比如示例输入[1] Hello world 示例输出[1] 你好世界第三分片不要太大。单次请求文本控制在 2000 字符以内超过后模型容易漏翻或合并段落。虽然多几次请求但质量更可控。第四遇到异常结果做重试。如果某段译文明显不对比如长度只有原文的十分之一或者全是英文自动重试一次。重试时把温度再调低通常能拿到正常结果。5.3 页面兼容性问题的处理不同网站的 DOM 结构差异很大有些页面翻译后会出问题。我遇到过的典型情况单页应用SPA动态加载内容。比如 React、Vue 写的网站页面内容是通过 JS 动态渲染的。翻译时如果只抓取初始 DOM会漏掉后续加载的内容。解决方案是用MutationObserver监听 DOM 变化有新文本节点时自动翻译。但要注意防抖避免频繁触发。iframe 嵌套页面。有些网站把内容放在 iframe 里content script 默认只注入顶层页面。需要在 manifest 里加all_frames: true让脚本注入所有 frame。但跨域 iframe 仍然无法访问这是浏览器安全限制无解。代码高亮插件干扰。有些技术博客用 Prism.js 或 Highlight.js 做代码高亮这些插件会把代码拆成很多 span 标签。我的过滤规则里已经跳过了code和pre但如果代码没有用这些标签包裹就可能被误翻。这种情况只能靠用户手动排除或者在设置里加一个“跳过选择器”的配置项。5.4 性能优化的几个实用技巧整页翻译的性能瓶颈主要在 API 请求上。除了分片合并还有几个优化点并发控制。不要一次性把所有分片都发出去容易触发限流。我设的是最多 3 个并发用 Promise 池控制。实测下来3 并发比串行快一倍多又不会触发 429。缓存译文。同一段文本如果之前翻译过直接读缓存不用再请求 API。用Map在内存里存页面刷新后失效。如果想持久化可以存到chrome.storage.local但要注意容量限制。懒翻译。只翻译视口内的内容滚动到哪翻到哪。这个方案对长页面很友好但实现复杂度高需要监听滚动事件、计算元素位置。我目前没做因为分片批量翻译已经够快了。跳过已翻译内容。给翻译过的节点加一个>document.addEventListener(mouseup, async (e) { const selection window.getSelection(); const text selection.toString().trim(); if (!text || text.length 2) return; const range selection.getRangeAt(0); const rect range.getBoundingClientRect(); // 显示浮层 const popup document.createElement(div); popup.className ai-translate-popup; popup.style.left ${rect.left}px; popup.style.top ${rect.bottom 8}px; popup.textContent 翻译中...; document.body.appendChild(popup); // 请求翻译 const result await translateText(text); popup.textContent result; });浮层的样式要用z-index: 2147483647确保在最上层同时加box-shadow和圆角视觉上更舒服。点击页面其他位置时移除浮层。6.2 多语言支持与自动检测默认翻译成中文但有时候需要翻译成其他语言。可以在设置里加一个目标语言选项支持英语、日语、韩语、法语、德语等。提示词里把“翻译成中文”改成动态变量即可。源语言检测可以交给大模型做在提示词里加一句“自动检测源语言”。但这样会增加 token 消耗。更经济的做法是用简单的字符集判断如果文本中中文字符占比超过 30%认为是中文跳过翻译如果包含西里尔字母可能是俄语包含阿拉伯字母可能是阿拉伯语。粗略判断足够用准确率交给大模型兜底。6.3 翻译历史与生词本每次翻译的结果可以存到chrome.storage.local形成一个翻译历史。用户可以在 popup 里查看最近翻译的段落方便回顾。如果加上生词本功能把划词翻译的单词和释义存下来就变成了一个简易的语言学习工具。存储结构设计{ history: [ { source: Hello world, target: 你好世界, time: 1700000000000 }, // ... ], vocabulary: [ { word: hello, meaning: 你好, context: Hello world, time: 1700000000000 } ] }历史记录限制最多 500 条超出后删除最旧的。生词本不限制但提供导出功能可以导出成 CSV 或 Anki 格式。6.4 自定义提示词模板高级用户可能想自己调提示词。可以在设置页面加一个文本框让用户自定义系统提示词。默认填入我调好的模板用户修改后保存。这样既照顾了小白也给折腾党留了空间。提示词模板里可以用的变量{targetLang}目标语言、{sourceLang}源语言可选。替换后再发给 API。const systemPrompt template .replace({targetLang}, config.targetLang || 中文) .replace({sourceLang}, config.sourceLang || 自动检测);7. 我踩过的坑与最终建议这个项目我从零开始搭前后迭代了十几个版本踩的坑不少。最大的一个坑是Manifest V3 的 service worker 休眠问题。一开始我把 API 配置存在 background 的全局变量里结果 service worker 休眠后变量丢失翻译请求全部失败。排查了半天才意识到是生命周期问题改成每次从chrome.storage读取后就好了。第二个坑是文本节点替换后的布局错乱。有些网站用text-overflow: ellipsis做截断翻译后文本变长省略号位置不对。解决方案是翻译后给元素加一个title属性把完整译文放进去鼠标悬停能看到全文。第三个坑是API 限流。免费额度的 API 通常有 QPS 限制并发一高就 429。我的做法是加一个简单的令牌桶限流器控制请求速率。具体实现就是维护一个时间戳队列每次请求前检查最近一秒内的请求数超过阈值就await sleep。如果你打算动手做我的建议是先跑通最小可用版本再逐步加功能。不要一上来就追求完美先把“提取文本-调用 API-替换译文”这个核心链路跑通哪怕只支持一个网站、只翻译一段文字。跑通之后再考虑分片、并发、缓存、划词这些进阶功能。这样每一步都有正反馈不容易半途而废。API 服务商的选择上我目前主力用智谱的 GLM-4-Flash免费额度大翻译质量稳定响应速度也快。DeepSeek 作为备用偶尔对比一下效果。两家都是 OpenAI 兼容接口切换成本几乎为零。如果你手头有其他的免费额度渠道改一下 baseUrl 和 model 就能用代码完全不用动。最后再分享一个小技巧翻译前先备份原始文本。在替换节点之前把原始文本存到节点的>
