沉浸式翻译接入 OpenAI 兼容 API：网页、PDF 与字幕翻译完整教程¶

最后核验：2026-07-14

适用范围：沉浸式翻译浏览器扩展当前版

推荐方式：使用 OpenAI 翻译服务的自定义地址，先小页面测试再翻译长文档

← 返回教程目录

[!NOTE] 本文适用于任何符合对应协议的 API。还没有测试 Key 时，可查看教程配套 API。

1. 适合什么场景¶

沉浸式翻译是一款浏览器翻译扩展，主要能力包括：

网页双语对照翻译；
鼠标悬停、划词和输入框翻译；
PDF、EPUB 与文档翻译；
视频和字幕文件翻译；
自定义翻译服务、AI Prompt 与术语；
按网站设置不同翻译规则。

接入 OpenAI 兼容 API 后，页面文本会分段发送给所选模型。它不是聊天客户端：接口需要兼容 Chat Completions，并能稳定处理大量短文本请求。

2. 安装扩展¶

官方支持 Chrome、Edge、Firefox、Safari，并提供 Android、iOS 与手动安装方式。优先从浏览器官方商店安装，以便自动更新。

安装后：

把扩展固定到浏览器工具栏；
打开任意普通网页；
点击扩展图标确认面板能打开；
Safari 首次使用时到扩展管理中启用，并授予需要的网站访问权限；
不要用浏览器商店页或浏览器内部页面做首次测试，这类页面通常禁止扩展运行。

3. 准备三项信息¶

API Key：<你的API-Key>；
模型 ID：<你的模型ID>；
OpenAI 兼容 Base URL：https://<你的-api-域名>/v1。

沉浸式翻译的 OpenAI“自定义地址”按官方示例接受完整请求地址，因此通常填写：

https://<你的-api-域名>/v1/chat/completions

这里与许多聊天客户端只填写 /v1 的规则不同。若你当前版本的字段明确标注为 Base URL，或 API 控制台提供了沉浸式翻译专用地址，应以字段说明和控制台地址为准。

4. 配置 OpenAI 翻译服务¶

不同版本和语言下菜单文字会略有变化，常见路径是：

点击浏览器工具栏中的沉浸式翻译；
打开 设置 或 Options；
进入 翻译服务 / 基本设置；
选择 OpenAI；
填入 API Key；
展开 更多设置；
在 自定义 API 地址 / Customized address 填入完整 Chat Completions URL；
在模型选择中手动填写或选择准确模型 ID；
保存设置。

推荐配置模板：

字段	建议值
翻译服务	OpenAI
API Key	`<你的API-Key>`
自定义地址	`https://<你的-api-域名>/v1/chat/completions`
模型	`<你的模型ID>`
每秒请求数	首次设为 1～3，稳定后逐步提高
Temperature	低值，优先保持翻译稳定

不要把 ChatGPT 网页账号、会员密码或浏览器 Cookie 填进 API Key。网页会员与 API 是两套服务。

5. 最小化验证¶

先不要翻译 PDF 或整本电子书：

打开一篇只有数段文字的公开网页；
选择目标语言；
点击 翻译；
确认页面出现原文和译文；
检查专有名词、数字、链接和段落结构；
打开 API 控制台核对是否产生一条或少量请求；
再测试一篇稍长文章。

默认快捷键通常包括：

Alt+A：翻译或切换原文
Alt+W：翻译整个页面

快捷键冲突时可在扩展的快捷键管理中修改。

6. Base URL 与完整端点怎么判断¶

先分清两个概念：

Base URL： https://<你的-api-域名>/v1
完整端点： https://<你的-api-域名>/v1/chat/completions

判断方法：

字段叫“自定义地址 / API URL”，官方 OpenAI 页面又以完整 Azure Chat Completions URL 为例时，优先填完整端点；
字段明确叫“Base URL”时填到 /v1；
出现 404 时，检查是否少了或重复了 /chat/completions；
不要写成 /v1/models，翻译实际需要发送聊天补全请求。

7. 模型选择建议¶

翻译模型更看重：

指令遵循和忠实度；
多语言能力；
对 YAML/结构化批量文本的稳定输出；
速度与并发限制；
上下文长度；
单位 Token 成本。

首次使用优先选择速度快、价格适中、稳定遵守格式的模型。推理能力很强但响应慢的模型，不一定适合大量页面分段翻译。

模型 ID 必须与 API 控制台一致，不要把展示名、产品系列名或自己起的昵称当作模型 ID。

8. 请求频率与长文档¶

网页翻译会把页面拆成多段并并发请求。官方文档建议出现 429 时降低每秒请求数，长文档场景可先降到约 5 次/秒或更低。更稳妥的起点是 1～3 次/秒。

推荐顺序：

小网页：1～3 次/秒；
稳定后逐步增加；
429 时立即降低；
PDF、EPUB、字幕使用比普通网页更保守的速率；
超长 PDF 可按官方 FAQ 建议拆成少于 100 页的部分再处理；
避免失败后高速连续重试。

提高并发只会缩短等待时间，不会降低总 Token 消耗。

9. 多 Key 负载均衡¶

官方 OpenAI 服务配置支持在 Key 输入框中用英文逗号分隔多个 Key：

<API-Key-1>,<API-Key-2>

使用前确认：

每个 Key 都属于你或已获授权；
每个 Key 都有目标模型权限；
不混用生产与测试 Key；
任意一个 Key 失效时及时移除；
平台已经在服务端提供负载均衡时，通常只填一个平台 Key 更容易审计和限额。

不要从网络收集或共享来历不明的 Key。

10. 高级配置¶

在 开发者设置 → 编辑完整用户配置 中，可以进一步调整参数。编辑前先导出或复制当前配置。

降低随机性¶

{
  "translationServices": {
    "openai": {
      "temperature": 0.2
    }
  }
}

调整请求超时¶

{
  "translationServices": {
    "openai": {
      "requestTimeout": 60000
    }
  }
}

时间单位为毫秒。过短会频繁超时，过长会让失败任务长时间卡住。

调整并发和单次文本量¶

官方高级配置支持：

limit：每秒请求数；
maxTextGroupLengthPerRequest：单次合并的文本段数；
maxTextLengthPerRequest：单次请求的文本长度；
apiUrl：自定义服务地址。

这些字段会影响成功率、速度和上下文。每次只调整一个参数并用同一网页对比结果。

11. 自定义 AI Prompt¶

沉浸式翻译支持为 AI 服务设置自定义翻译提示词，常见变量包括：

变量	含义
`{{text}}`	待翻译文本
`{{from}}`	源语言
`{{to}}`	目标语言
`{{content_type}}`	HTML 或纯文本
`{{title_prompt}}`	页面标题上下文
`{{summary_prompt}}`	页面摘要上下文
`{{terms_prompt}}`	术语上下文

一个简单原则：要求只输出译文、保留占位符与格式，不要让模型回答原文中的问题。

修改提示词后要测试：

HTML 标签和占位符是否保留；
多段批量结果的顺序是否一致；
数字、代码和 URL 是否被错误改写；
字幕时间轴是否完整；
原文看似指令时，模型是否仍只执行翻译。

12. 术语与专业翻译¶

官方 FAQ 显示 1.16.1+ 支持 AI 术语功能。适合：

产品名和品牌名固定译法；
医学、法律、金融等领域术语；
人名、地名、缩写保持一致；
团队统一文风。

术语太多或互相冲突会降低翻译质量。先维护几十个高频术语，用固定样本回归测试，再逐步扩展。

13. 网页、PDF 与字幕差异¶

网页¶

默认“智能翻译”优先正文；侧栏遗漏时可临时使用“翻译整个页面”。整页模式请求更多，成本也更高。

本地 PDF / HTML¶

Chromium 浏览器需要在扩展管理中启用“允许访问文件网址”。Safari 和 Firefox 对本地文件访问限制更严格，可使用官方文档翻译入口。

字幕¶

桌面端支持字幕文件翻译和部分网站的双语字幕下载。翻译前保留原始字幕文件，检查时间轴、换行和说话人标记。

图片¶

图片翻译还涉及 OCR。识别错字与模型翻译错误是两类问题，应先检查识别文本。

14. 常见错误¶

401 Unauthorized¶

Key 填错、已失效或带首尾空格；
Key 没有模型权限；
把网页会员信息当成 API Key；
自定义接口不接受 Bearer 鉴权。

404 Not Found¶

只填了 /v1，但当前字段需要完整 /chat/completions；
已填完整端点，扩展或代理又重复拼接；
URL 路径写错或反向代理重写异常。

先核对当前界面的字段名称，再按第 6 节切换 URL 形式。

429 Too Many Requests¶

每秒请求数过高；
PDF/电子书一次产生大量并发；
Key 额度或速率受限。

降低 limit，等待一段时间后从小页面重试。

400 / 输出格式错误¶

模型不稳定遵循批量翻译格式；
自定义 Prompt 破坏了 YAML 或占位符；
单次文本过长；
接口不支持扩展发送的参数。

恢复默认 Prompt，缩小每次请求长度，并换用纯文本页面测试。

翻译按钮无反应¶

当前是浏览器内部页、商店页或第三方扩展页；
扩展没有网站访问权限；
页面安装扩展前已打开，需刷新；
Opera 等浏览器需要额外允许访问搜索结果页。

译文重复、漏段或错位¶

页面由动态脚本频繁更新；
PDF 文本层或 OCR 有问题；
模型未按批量格式返回；
自定义 Prompt 或术语规则冲突。

用默认配置和静态网页复测，以区分页面解析问题与 API 问题。

15. 隐私与安全¶

接入外部 API 意味着被翻译的文本可能会发送到该服务。使用前应确认数据政策和组织规定。

不翻译含密码、令牌、私钥或未公开商业资料的页面；
不在截图、录屏、同步配置或工单中暴露 Key；
给翻译单独创建 Key 并设置额度；
在共享浏览器配置中避免保存个人 Key；
离职、设备丢失或怀疑泄露时立即撤销 Key；
使用 HTTPS 地址，不通过明文 HTTP 传输云端 Key；
谨慎启用整页翻译，页面侧栏和隐藏区域也可能被处理。

16. 备份、回滚与卸载¶

修改高级配置前¶

复制或导出完整用户配置；
记录当前翻译服务、模型和自定义地址；
每次只改一个字段；
用同一测试网页验证。

快速回滚¶

切回扩展内置的其他翻译服务；
恢复原模型、Prompt 和请求频率；
删除错误的自定义地址；
移除 API Key；
高级配置损坏时恢复备份或使用界面重置；
商店版异常时先更新，再考虑卸载重装。

卸载扩展前先撤销不再使用的 API Key。仅卸载扩展不会自动让服务器端 Key 失效。

17. 官方资料¶

求助时请提供浏览器与扩展版本、翻译服务、脱敏后的 URL 结构、模型 ID、HTTP 状态码和出现问题的公开测试页面。务必删除 API Key、Cookie、私密原文和完整账户信息。