NextAI Translator 完整使用与源码解析：基于 ChatGPT API 的跨平台划词翻译与润色工具-编程实验室

NextAI Translator 完整使用与源码解析：基于 ChatGPT API 的跨平台划词翻译与润色工具

【免费下载链接】nextai-translator基于 ChatGPT API 的划词翻译浏览器插件和跨平台桌面端应用 - Browser extension and cross-platform desktop application for translation based on ChatGPT API.项目地址: https://gitcode.com/GitHub_Trending/op/nextai-translator

导读

NextAI Translator 是一款基于 ChatGPT API 的划词翻译浏览器插件与跨平台桌面端应用，支持翻译、润色、总结三种核心模式，覆盖 55 种语言的互译，并内置截图翻译、生词本、TTS 等实用功能。本文以仓库 README-CN.md 为主干，结合 src/common/engines、src/common/translate.ts、CLIP-EXTENSIONS-CN.md 等源码与配置，完整讲解其特性、API 准备、Windows/macOS 安装排障、浏览器插件与桌面端划词扩展的接入方式，以及 Azure OpenAI Service 的底层配置原理，帮助读者既能在 10 分钟内跑通全部功能，也能理解其请求构造与多服务商引擎设计。

项目背景：为什么会有这个轮子

作者最初开发了一个基于 ChatGPT API 的 macOS 全局划词翻译插件（Bob 插件），但 Bob 仅支持 macOS，大量非 macOS 用户无法使用。为了让更多用户享受到基于 ChatGPT API 的划词翻译体验，作者启动了本仓库，将能力扩展为浏览器插件与桌面端应用双形态。

另外值得注意的一点：项目曾因收到 OpenAI 公司的品牌名称所有权警告而由原名更名为nextai translator，README 顶部也保留了这段说明。因此，仓库中的源码路径、配置项命名里仍能看到历史遗留的openai-translator痕迹（例如 clip-extensions/snipdo/nextai-translator.json 中的 identifier 为xyz.yetone.apps.openai-translator.clip-extensions.snipdo，macOS 划词插件脚本也通过/tmp/openai-translator.sock与主程序通信），阅读时需要注意这些命名并不代表当前产品名。

核心特性总览

README 列出了该项目的十大特性，逐条说明如下：

三种翻译模式：翻译（translate）、润色（polishing）、总结（summarize）。在 src/common/translate.ts 中可以看到模式类型定义还额外扩展了analyze（语法分析）、explain-code（代码解释）与big-bang（基于生词本生成短文），说明源码实现比 README 列举的模式更为丰富。
55 种语言互译、润色与总结：语言配置集中在 src/common/lang 目录，每种语言带有角色提示词（rolePrompt）与音标标注方式等配置。
实时（流式）翻译：以最快速度响应用户。请求通过 SSE 流式返回，见 src/common/engines/abstract-openai.ts 中的fetchSSE调用与onMessage增量回调。
自定义翻译文本：支持在设置中自定义提示词，翻译时通过${sourceLang}、${targetLang}、${text}占位符注入语言与文本（见 src/common/translate.ts）。
一键复制：翻译结果面板提供复制按钮。
TTS 朗读：TTS 实现位于 src/common/tts，包含 EdgeTTS 与本地 TTS（LocalTTS）两种提供方；源码 src/common/utils.ts 显示 Edge TTS 公共端点已失效，因此用户若曾选择 EdgeTTS 会被自动切换到本地引擎。
桌面端应用：基于 Tauri（Rust）构建，覆盖 Windows、macOS、Linux 全平台，桌面端源码位于 src-tauri。
截图翻译：通过 src-tauri/src/ocr.rs 的 OCR 能力配合截图窗口（src/tauri/windows/ScreenshotWindow.tsx）实现。
生词本：支持收集生词，并可基于生词本中的单词生成帮助记忆的内容（即big-bang模式，由 src/common/translate.ts 构造写作提示词）。
多 LLM 服务商：除 OpenAI 外，还支持 Azure OpenAI Service、MiniMax、TeamoRouter 等。

架构总览：既是浏览器插件也是桌面端应用

仓库采用一套共享业务核心（src/common）加多端壳的架构：

浏览器插件（Chromium / Firefox）：入口在 src/browser-extension，包括后台脚本 background/index.ts、划词浮层 content_script/InlineLookupContainer.tsx、设置页 options 与弹窗 popup；浏览器清单由 manifest.ts 生成。
桌面端应用：基于 Tauri（前端源码在 src/tauri，Rust 侧在 src-tauri/src），提供翻译窗口、截图窗口、设置窗口、生词本窗口等多个独立窗口。
共享核心：翻译引擎、设置存储、历史记录、生词本、TTS、i18n 等全部沉淀在 src/common，浏览器端与桌面端复用同一套逻辑，保证双端行为一致。
Safari 扩展：另有 src-safari 提供 Web Extension 工程，可在 Xcode 中构建。

使用准备：API Key 与服务商选择

在安装使用之前，需要准备以下三类凭证之一：

（推荐）TeamoRouter：一个兼容 OpenAI 协议的 LLM 网关，一个 API Key 即可调用 OpenAI、Claude、Gemini 等模型。设置里将服务商选择为TeamoRouter并填入 API Key 即可使用，无需额外配置 Base URL。
（必须）OpenAI API Key 或 Azure OpenAI Service API Key：在 OpenAI 平台或 Azure 门户申请。
（可选）OpenAI API Proxy：无法直接访问 OpenAI 时，可在设置中填入代理的 Base URL 与 API Key。

服务商在源码中的实现

在 src/common/engines/index.ts 中，Provider类型目前定义了 17 种服务商：OpenAI、ChatGPT、Azure、MiniMax、Moonshot、Gemini、Ollama、Groq、Claude、Kimi、ChatGLM、Cohere、DeepSeek、Cerebras、TeamoRouter、OpenRouter、LiteLLM。每种服务商对应一个引擎类，统一实现IEngine接口，并通过providerToEngine映射表与getEngine(provider)工厂方法按需实例化（src/common/engines/index.ts）。

绝大多数 OpenAI 兼容服务商继承自AbstractOpenAI抽象基类（src/common/engines/abstract-openai.ts），只需覆写四个方法即可接入：getAPIModel()（模型名）、getAPIKey()（API Key，支持逗号分隔多个 Key 随机轮换）、getAPIURL()（Base URL）、getAPIURLPath()（路径）。以 OpenAI 引擎为例（src/common/engines/openai.ts）：

async getAPIKey(): Promise<string> { const settings = await getSettings() const apiKeys = (settings.apiKeys ?? '').split(',').map((s) => s.trim()) const apiKey = apiKeys[Math.floor(Math.random() * apiKeys.length)] ?? '' return apiKey }

可以看到多个 API Key 以英文逗号分隔填入时，每次请求会随机抽取一个，这为多账号负载分担提供了基础。

默认端点与自动路由

src/common/utils.ts 定义了默认值：

export const defaultAPIURL = 'https://api.openai.com' export const defaultAPIURLPath = OPENAI_CHAT_COMPLETIONS_API_PATH export const defaultProvider = 'OpenAI' export const defaultAPIModel = OPENAI_PREFERRED_DEFAULT_MODEL

其中OPENAI_CHAT_COMPLETIONS_API_PATH与默认模型定义在 src/common/openai-api-path.ts：

export const OPENAI_CHAT_COMPLETIONS_API_PATH = '/v1/chat/completions' export const OPENAI_RESPONSES_API_PATH = '/v1/responses' export const OPENAI_PREFERRED_DEFAULT_MODEL = 'gpt-5-nano'

值得注意的是，AbstractOpenAI会根据模型名自动在 Chat Completions 与 Responses 两套 API 之间切换（src/common/engines/abstract-openai.ts）：gpt-5*、o*、gpt-4o*、gpt-4.1*、gpt-4.5*等模型会被推荐走/v1/responses，其余走/v1/chat/completions；同时根据模型家族自动构造请求参数——传统gpt-3/4使用temperature: 0, top_p: 1, frequency_penalty: 1, presence_penalty: 1, stream: true，o 系列与 gpt-5 pro 使用reasoning_effort，gpt-5.1+ 则退化为最小参数集以避免废弃参数报错（src/common/engines/abstract-openai.ts）。

安装指南

Windows 桌面端手动安装

在 Releases 页面下载以.exe结尾的安装包；
双击安装包完成安装；
若系统提示不安全，点击更多信息->仍要运行继续安装；
安装完成后即可使用。

macOS 桌面端手动安装

在 Releases 页面下载对应芯片的.dmg安装包：Apple Silicon 机器务必使用 aarch64 版本，并注意执行下文xattr指令；Intel 机器使用 x86_64 版本；
双击安装包，将NextAI Translator拖动到Applications文件夹；
开始使用。

macOS 常见故障排除

场景一：提示"无法打开，因为无法验证开发者"

点击Cancel按钮，然后前往设置->隐私与安全性，点击仍要打开，在弹出的窗口中点击打开即可。此后打开 NextAI Translator 不会再出现弹窗告警。

场景二：隐私与安全性中没有对应选项，或 Apple Silicon 版本启动时提示文件损坏

打开Terminal.app，执行以下命令（中途可能需要输入密码），然后重启应用：

sudo xattr -d com.apple.quarantine /Applications/NextAI\ Translator.app

场景三：每次打开都遇到权限提示，或快捷键划词翻译无法执行

前往设置->隐私与安全性->辅助功能，先删除 NextAI Translator，然后重新添加即可。这是因为全局快捷键监听需要辅助功能权限，删除重加会重置授权状态。

浏览器插件安装

在浏览器插件市场安装此插件（Chrome Web Store / Firefox Add-on）；
点击浏览器插件列表里的 NextAI Translator 图标，把获取的 API KEY 填入弹出的配置界面；
刷新浏览器页面，即可享受划词翻译体验。

桌面端划词扩展安装

桌面端应用本身无法像浏览器那样直接拿到选中文本，因为各操作系统都没有统一的获取选中文本 API。常见的剪切板方案会在部分应用中造成剪切板混乱，在 macOS 上还会因未选中文本就按 cmd+c 发出警告声。为此，项目为各平台成熟的划词软件开发了专用插件，详见 CLIP-EXTENSIONS-CN.md：

macOS 使用 PopClip：安装 PopClip 后，下载nextai-translator.popclipextz并双击，点击Install "NextAI Translator"完成安装，然后在 PopClip 中启用该扩展；
Windows 使用 SnipDo：安装 SnipDo 后，下载nextai-translator.pbar并双击安装，在 SnipDo 设置页面中启用 NextAI Translator，建议只保留这一个扩展项以避免误触。

这些插件与主程序通过本机 socket 通信。以 PopClip 插件为例（clip-extensions/popclip/nextai-translator.sh）：

send_text() { curl -d "$POPCLIP_TEXT" --unix-socket /tmp/openai-translator.sock http://nextai-translator } if ! send_text; then open -g -a NextAI\ Translator sleep 2 send_text fi

逻辑很清晰：先把选中的文本（$POPCLIP_TEXT）通过 Unix socket 发给主程序；如果失败（主程序未运行），则后台拉起应用，等待 2 秒后重试。SnipDo 插件则通过 PowerShell 脚本（clip-extensions/snipdo/nextai-translator.ps1）实现同样的功能，其清单 clip-extensions/snipdo/nextai-translator.json 声明了插件名称、图标与脚本文件。

配置 Azure OpenAI Service

在设置中将服务商切换为Azure后，需要填写以下信息。README 给出了 URL 与路径的拼接公式：

const API_URL = `https://${resourceName}.openai.azure.com` const API_URL_PATH = `/openai/deployments/${deployName}/chat/completions?api-version=${apiVersion}`

参数说明：

resourceName：你的 Azure OpenAI Service 资源名称；
deployName：模型部署名称，更改部署名称即可切换模型；
api-version：2023-05-15或更新的版本（以 Azure 官方支持的 API 版本列表为准）。

源码中的 Azure 引擎细节

在 src/common/engines/azure.ts 中可以看到 Azure 引擎与标准 OpenAI 引擎的差异：

鉴权头：Azure 使用api-key请求头而非Authorization: Bearer（src/common/engines/azure.ts）；
模型列表：Azure 的模型由部署决定，无法通过/v1/models拉取，因此listModels直接返回内置的候选列表（含gpt-4o (recommended)、gpt-4-turbo、gpt-3.5-turbo系列等），而 OpenAI 引擎则会真实调用GET {apiURL}/v1/models过滤后返回（src/common/engines/abstract-openai.ts）；
请求体：会额外携带max_tokens: settings.azMaxWords（src/common/engines/azure.ts）；
非 Chat API 兼容：isChatAPI()会检查路径中是否包含/chat/completions（src/common/engines/azure.ts），若不包含则走 Completion 兼容模式，使用<|im_start|>风格的 prompt 模板（见 src/common/engines/abstract-openai.ts）。

另外，当服务商为 Azure 且用户未单独填写 Azure 字段时，设置系统会自动用通用字段兜底：azureAPIKeys回退到apiKeys、azureAPIURL回退到apiURL、azureAPIURLPath回退到apiURLPath（src/common/utils.ts），减少了重复配置。

翻译工作流：从选中文本到流式输出

一次划词翻译的完整链路可以从 src/common/translate.ts 梳理出来：

模式分发：根据action.mode（translate / polishing / summarize / analyze / explain-code / big-bang）构造不同的角色提示词（rolePrompt）与命令提示词（commandPrompt）。例如润色模式使用"improve clarity, conciseness, and coherence, making them match the expression of native speakers"；总结模式强制要求使用目标语言输出。
语言注入：通过getLangConfig读取目标语言的提示词配置，把源语言名、目标语言名替换进提示词模板。
单词模式增强：当文本是一个单词且目标语言为中文时，会触发词典式输出——要求返回原始形态、语种、音标、所有含义（含词性）、至少三条双语例句与词源（src/common/translate.ts）。这解释了生词本与单词卡片功能为什么能提供如此详细的释义。
服务商与模型解析：优先使用 Action 级配置的 provider/model，否则回退到全局设置（src/common/translate.ts），实现了"不同快捷操作可用不同模型"的灵活配置。
引擎调用：通过getEngine(effectiveProvider)拿到引擎实例并调用sendMessage，最终由 src/common/engines/abstract-openai.ts 的fetchSSE发起流式请求，逐块把增量内容经onMessage回调渲染到界面。

设置项（API Key、URL、路径、模型、代理、TTS、快捷键等）统一由 src/common/utils.ts 的settingKeys清单从browser.storage.sync读取并填充默认值，这就是为什么清空某个字段后应用仍能恢复默认端点正常工作。

许可证

本项目采用 MIT 许可证，详见 LICENSE。README 同时保留了 Star 历史图表，读者可自行查看仓库的演进轨迹。

总结

从 README 到源码，NextAI Translator 的定位可以概括为三点：以 ChatGPT API 为核心引擎的翻译工具、浏览器插件与桌面端双形态、一套共享核心的多服务商适配架构。对于普通用户，按本文完成 API 准备、桌面端或浏览器插件安装、以及必要的 macOS 权限处理即可顺畅使用；对于开发者，src/common/engines 的AbstractOpenAI抽象基类与 src/common/translate.ts 的提示词构造逻辑是理解本项目、甚至二次开发新服务商适配器的最佳起点。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考