插件应用市场
AI Translate
AI Translate 是一款运行在 [uTools](https://u.tools/) 中的智能翻译插件，主打「文本翻译 + 划词翻译 + 图片 OCR 翻译 + 朗读」一站式体验，并内置翻译历史管理。插件加载即用
# AI Translate 使用文档
AI Translate 是一个 uTools 智能翻译插件，支持**文本翻译、图片 OCR 后翻译、文言文翻译、截图翻译、划词查词、译文朗读**，以及本地保存**翻译历史**。
插件本身没有构建步骤，也不是可直接在普通浏览器中运行的网页。运行时依赖 uTools 提供的插件入口、内置 AI、剪贴板和 `dbStorage` 能力。
---
## 1. 功能概览
| 功能 | 说明 |
| --- | --- |
| 文本翻译 | 手动输入、粘贴文本，或从 uTools 搜索框 / 划词传入文本 |
| 划词翻译 | 选中文字后通过 uTools「翻译选中」入口打开插件 |
| 图片翻译 | 读取剪贴板图片、图片文件，或在插件内粘贴 / 选择图片，经 OCR 识别后翻译 |
| 截图翻译 | 框选屏幕区域，主窗口隐藏，在选区处弹出透明浮窗原位显示原文与译文，可放大回主窗口继续编辑 |
| 文言文翻译 | 将文言文译为现代白话文（也可把外文译为文言文） |
| 译文朗读（TTS） | 朗读输入或译文，支持 OpenAI 兼容接口与火山引擎；关闭后主页不再显示朗读按钮 |
| 流式输出 | 自定义接口逐字显示译文；内置通道不支持时自动回退为整段返回 |
| 同步滚动 | 滚动左侧原文或右侧译文，另一侧按相同比例联动，始终对照同一段 |
| 富文本展示 | 自动识别 HTML 表格与 Markdown 并安全渲染，可切回原文 |
| 划词查词 | 选中待翻译区文字即弹卡片，给出释义与例句（可关闭） |
| 模型状态 | 主页顶部三枚独立 chip，分别检测翻译 / OCR / 朗读 的连通状态 |
| 翻译历史 | 可展开、复制、单条删除或清空，并可设置保留时长 |
| 方向自适应 | 阿拉伯语等 RTL 语言从右向左显示；蒙古语竖写 |
**两种翻译通道**：uTools 内置 AI，或自定义 OpenAI 兼容接口。
**OCR 识别**：调用支持图片输入的 OpenAI 兼容视觉模型，无 Tesseract 等本机 OCR 回退。
**支持的语言（16 种）**：简体中文、繁體中文、English、Français、Русский、日本語、한국어、Deutsch、Español、Português、Italiano、العربية（阿拉伯语）、ไทย、Tiếng Việt、文言文、蒙古语。源语言另支持「自动检测」（共 17 个选项）。其中文言文既可作源语言（古文今译）也可作目标语言（外文译文言）；阿拉伯语从右向左书写（RTL）；蒙古语为传统蒙文竖写。
---
## 2. 运行前准备
### 2.1 载入插件
1. 安装并打开 uTools。
2. 通过 uTools 开发者工具载入本项目的 `plugin.json`。
3. 在 uTools 中搜索或划词选「翻译」「翻译选中」「图片翻译」「翻译图片文件」、「截图翻译」「文言文翻译」「文言文翻译选中」进入插件。
项目是原生 HTML、CSS 和 JavaScript 结构，不需要执行 `npm install`、打包或构建。
> 不要直接双击 `index.html` 使用。普通浏览器中没有 `window.utools` 和预加载服务，翻译、OCR、朗读、复制及配置存储均无法正常工作。
### 2.2 模型要求
文本翻译至少需要以下一种能力：
- uTools 内置 AI；或
- 一个兼容 OpenAI `chat/completions` 请求格式的文本模型接口。
图片 OCR 必须另外配置一个兼容 OpenAI 多模态消息格式、且支持图片输入的视觉模型接口（例如本地运行的视觉语言模型服务）。即使只使用 uTools 内置翻译，图片识别仍需配置 OCR 模型。
译文朗读（TTS）需要配置一个 TTS 服务：
- OpenAI 兼容的语音合成接口（提供接口地址、API Key、模型与音色）；或
- 火山引擎语音合成（提供接口地址、API Key、资源 ID 与音色）。
---
## 3. 首次配置
点击主页右上角的齿轮进入设置。设置页从右侧滑出抽屉（不切换页面），按 **翻译模型 / OCR / 朗读 / 其他** 分为 4 个分组。测试按钮不写库，只有「保存配置」才持久化；切换 / 取消 / 退出均不写入 `dbStorage`。
### 3.1 翻译模型
#### uTools 内置
选择「uTools 内置」即可，无需填写接口地址、API Key 或模型名称。翻译请求通过 uTools 内置 AI 发出。
#### 自定义（仅 OpenAI 兼容）
| 字段 | 是否必填 | 说明 |
| --- | --- | --- |
| 接口地址 | 是 | 只填写基础地址，例如 `http://127.0.0.1:54321/v1` |
| API Key | 是 | 请求时以 `Authorization: Bearer ...` 发送 |
| 模型名称 | 是 | 填写服务实际暴露的模型标识 |
插件会自动在接口地址后追加 `/chat/completions`。**不要**填写完整的 `.../chat/completions` 地址，否则会得到重复后缀。
如果本地服务不校验鉴权，自定义翻译配置中仍需填写一个非空的 API Key 占位值，因为插件会校验该字段。
点击「测试连接」会用当前表单配置试译 `Hello`（使用正确的语言标识）。测试不会保存表单、修改现有配置，也不会写入翻译历史；只有「保存配置」才会持久化。
「模型名称」为「输入 + 下拉」组合框：点开后会自动向所填接口地址拉取可用模型列表（同一地址只拉一次），也可手动输入列表中没有的模型标识。
### 3.2 OCR 识别配置
| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| 接口地址 | `http://localhost:11434/v1` | 只填写基础地址，插件自动追加 `/chat/completions` |
| 模型名称 | 空 | 必须是支持图片输入的视觉模型 |
| API Key | 空 | 可选；本地无鉴权服务通常留空 |
| 超时时间 | `60000` ms | 模型较慢时可适当增大（范围 1000–600000） |
| Prompt | `Free OCR.` | 发给视觉模型的识别提示词 |
点击「测试 OCR」后，插件会生成一张包含 `AI Translate 测试 OCR 123` 的测试图，并使用当前表单配置识别。测试同样不会保存配置。
DeepSeek-OCR 系列对提示词较敏感。如果出现无识别内容、`completion_tokens=0` 或模型拒答，优先把 Prompt 恢复为简短英文 `Free OCR.`。
### 3.3 朗读（TTS）配置
- **服务开关**：关闭时插件不显示朗读按钮。
- **服务类型**：OpenAI 兼容 或 火山引擎，二者择一。
- **OpenAI 兼容**：填写接口地址、API Key、模型与音色（voice）。
- **火山引擎**：填写接口地址、API Key、资源 ID 与音色。
- 「音色 voice」为组合框：OpenAI 兼容模式点开后会自动拉取可用音色列表（需先填模型），火山引擎则手动填写发音人标识（如 `zh_female_qingxin`）。
- 关闭翻译窗口会自动停止正在进行的朗读，临时音频也会释放。
### 3.4 其他配置
**翻译行为**
- **自动翻译**：默认开启。开启后，文本进入待翻译区即翻译（受下方防抖控制）；关闭时清空结果，改用两个文本框中间的「译」按钮手动翻译。切换内置 / 自定义模式不会清空已填配置。
- **自动翻译防抖（毫秒）**：仅在自动翻译开启时可用，控制输入停顿多久才发起翻译（默认 500，范围 0–5000，0 即即时翻译）。可避免逐字输入时每次按键都调用模型；按量计费接口可保留防抖以省 token。
- **翻译后自动复制结果**：默认关闭。开启后译文自动写入剪贴板（与手动「复制」等价）。
- **划词查词**：默认开启。关闭后选中待翻译区文字不再弹出查词卡片。
- **流式输出译文**：默认开启。自定义接口下译文逐字显示；内置 utools.ai 不支持流式时自动回退为整段返回。
**默认语言**
- **默认源语言 / 默认目标语言**：新开页面时预选的语言，可设为「自动检测」或具体语言。目标语言设为「自动」（自动检测）时跟随系统语言（依 uTools 语言判断简体 / 繁体中文）。
**历史记录**
- **历史记录**：默认开启。关闭并保存后，会立即清空已有历史、停止继续记录，并隐藏主页历史面板。
- **历史保留时长**：可选不限、最近 1 小时、1 天、1 周或 1 月；无论选择哪一项，最多保存 100 条。
**主页面状态与交互**
- **显示模型状态**：默认开启。关闭后主页不再显示「翻译 / OCR / 朗读」三个连通性 chip，也不再发起任何连通性检测（省 token）。
- **同步滚动原文与译文**：默认开启。开启后，滚动一侧，另一侧按相同比例联动，始终对照同一段内容。
**截图翻译**
- **截图后浮窗显示原文**：默认开启。截图翻译浮窗在译文之外是否同时显示 OCR 识别的原文；关闭则仅显示译文。
- 该分组内另含三条使用提示：OCR 依赖、快捷键绑定指引、macOS 屏幕录制权限。
完成设置后点击「保存配置」。「取消」会放弃本次表单修改。
---
## 4. 文本翻译
### 4.1 在插件内翻译
1. 选择源语言；不确定时保留「自动检测」。
2. 选择目标语言，默认为「自动」（跟随系统语言）。
3. 在左侧待翻译区输入或粘贴文本。
4. 自动翻译开启时会立即翻译（受防抖控制）；关闭时点击两个文本框中间圆形的「译」按钮。
5. 点击右侧「复制」复制译文；若开启了自动复制，译文会直接进剪贴板。
6. 点击朗读按钮，可把译文（或原文）朗读出来。
**流式输出**：自定义接口下，译文会逐字显示，无需等待整段返回；内置通道不支持流式时自动整段返回。
**同步滚动**：开启后滚动任意一侧文本框，另一侧按相同比例联动，方便长文本逐段对照。
**交换语言**：源语言为「自动检测」时，交换按钮不可用；选择具体源语言后，点击交换按钮会同时交换源语言、目标语言、原文和译文。
### 4.2 从 uTools 调用
- **文本入口**：在 uTools 搜索框中输入或粘贴文本，选择「翻译」。
- **划词入口**：选中文字后，从 uTools 超级面板进入「翻译选中」。
- **文言文入口**：在 uTools 搜索框输入文言文，选择「文言文翻译」；或划词选「文言文翻译选中」。
插件重复进入同一个翻译页面时会保留当前输入、结果和语言选择，不会主动重置页面状态。
---
## 5. 图片 OCR 与翻译
可以通过以下方式识别图片：
- 在 uTools 中复制图片后选择「图片翻译」；
- 在 uTools 中传入图片文件后选择「图片翻译」；
- 在插件主页点击「图片」，再点击「选择图片」；
- 在左侧输入区、表格视图或图片面板获得焦点后，按 `Ctrl+V` / `Command+V` 粘贴图片。
识别流程为：读取图片 → 调用 OCR 视觉模型 → 将识别文字填入左侧 → 按「自动翻译」设置决定是否继续翻译。
一次通过 uTools 文件入口传入多张图片时，当前版本只处理第一张。
`plugin.json` 目前声明支持 PNG、JPG/JPEG、GIF 和 WebP 文件入口；OCR 服务层能可靠识别的 MIME 类型也是这几种。遇到其它格式时，优先转换为 PNG、JPEG 或 WebP 后再试。
---
## 6. 截图翻译
截图翻译让你在屏幕上框选一块区域，插件在选区位置原位弹出透明浮窗显示识别出的原文与译文，不打断当前工作；需要细看或继续编辑时，可一键放大回主窗口。
### 6.1 如何触发
- 主页语言栏右侧的「截图」按钮（需先在 OCR 配置中开启本地 OCR 模型；未开启时该按钮自动隐藏）；
- 在 uTools 中通过全局快捷键调用「截图翻译」（在 uTools 菜单「设置 → 快捷键 → 插件」里为「截图翻译」命令绑定组合键，插件本身无法在代码内注册系统热键）。
### 6.2 工作流程
1. 点击「截图」或触发快捷键后，主窗口立即隐藏，整个识别翻译过程主窗口都不露面；
2. 框选屏幕区域，松手那一刻在光标处弹出「识别翻译中…」加载浮窗（即时反馈，无需干等）；
3. 后台并行完成 OCR 识别与翻译，结果算好后在同一位置弹出结果浮窗；
4. 结果浮窗关闭时主窗口保持隐藏；只有点击「放大」回到主窗口时，才会重新显示主窗口并回填截图、原文、译文。
### 6.3 浮窗操作
结果浮窗为透明无边框窗口，大小贴合选区内容、可手动拖拽边缘缩放：
- 左上「放大」图标：把截图、原文、译文回填到主窗口并重新显示主窗口（不退出插件）；
- 右上「X」/ 按 `Esc` / 点击浮窗外的透明区域：直接退出插件，主窗口保持关闭；
- 「复制译文」「复制原文」按钮：仅在 OCR 开启时显示（OCR 关闭则截图翻译无产出），点击后按钮短暂变为「已复制」；
- 译文同样支持表格 / Markdown 富文本渲染（与主页一致）；原文与译文的显示方向也会随语言自动适配（见第 9 节）。
> 浮窗关闭或退出后，主窗口不会自动弹出；若想回到主窗口查看或编辑，请使用左上「放大」图标。
### 6.4 相关设置
- 「截图后浮窗显示原文」（其他配置）：默认开启，浮窗在译文之外同时显示 OCR 原文；关闭则只显示译文。
- 截图翻译同样遵循「翻译后自动复制结果」设置：若开启，译文会直接写入剪贴板。
### 6.5 依赖与权限
截图翻译依赖本地 OCR 视觉模型，且 macOS 首次使用会请求「屏幕录制」权限（设置路径：系统设置 → 隐私与安全性 → 屏幕录制，勾选 uTools 后完全退出重开）。若截取为黑屏，请检查该权限是否已授予。
---
## 7. 文言文翻译
通过「文言文翻译」入口，将文言文译为现代白话文；选择具体目标语言为「文言文」时，也可把外文译为文言文。其余输入、翻译、复制、朗读、历史行为与文本翻译一致。
---
## 8. 表格与富文本
当待翻译文本或翻译结果中包含有效的 HTML 表格结构，例如 `
`，插件会显示可视化表格，并保留表格前后的普通文字：
- 点击「查看原文」可查看模型返回的原始文本；
- 点击「查看表格」可切回表格视图；
- 表格会经过白名单重建，仅保留表格行、单元格、合并行列和纯文本，不会直接执行模型返回的 HTML 或脚本。
如果模型返回的标签不完整且无法形成有效单元格，插件会降级为普通文本展示。
除了 HTML 表格，待翻译区和结果区还会渲染 Markdown 语法（标题、列表、引用、代码块、分隔线、GFM 表格）。当内容被识别为富文本时，底栏会显示「已识别为表格」或「已识别为 Markdown」，点击「查看原文」可查看模型返回的原始文本。所有富文本都经过白名单重建，只保留安全标签，不会直接执行模型返回的 HTML 或脚本。
---
## 9. 语言方向与排版
插件会根据所选语言自动调整文字方向，无需手动设置：
- **RTL（从右向左）**：阿拉伯语（العربية）的原文 / 译文以从右向左书写与排版，输入框与结果区方向自动适配。
- **竖写**：蒙古语（蒙古语）使用传统蒙文竖排（字从上到下、列从左到右）；仅结果展示区生效，输入框保持横排。
- **系统语言匹配**：目标语言设为「自动检测」时，依 uTools 语言判断简体 / 繁体中文；其它语言按系统区域语言自动匹配（文言文、蒙古语不参与系统自动匹配）。
---
## 10. 划词查词
划词查词仅在待翻译区生效（结果区整体关闭）。选中文字即弹出浮动卡片，给出单词释义与例句（可在设置中关闭）。选中文本长度上限 200 字，选词后会有约 500ms 的稳定窗口再触发查词，避免拖动过程中频繁请求。
查词 prompt 要求模型返回纯 JSON（无例句解释前缀），渲染层仅做空值过滤、查询词高亮与字符串数组兼容，正确性由 prompt 保证。
---
## 11. 翻译历史
主页底部的「翻译历史」默认收起，点击横条展开：
- 点击一条记录：复制该条译文；
- 点击记录右侧的 `×`：删除该条记录；
- 点击「清空」，再点击「确认清空？」：清空全部记录；
- 按 `Esc`：收起历史面板。
连续自动翻译时，2 分钟内、源语言和目标语言都相同且原文互为前缀的输入会合并为一条记录，避免逐字输入产生大量中间历史。完全相同的记录会移动到最前并刷新时间。历史最多保存 100 条，保留时长可在「其他配置」中设置。
---
## 12. 模型状态
主页顶部有 3 个独立 chip，分别检测「翻译 / OCR / 朗读」模型的连通状态，各自独立显示：
- 灰（检测中 / 未启用）：功能未开启（如未开朗读）时显示「未启用」——灰色不等于故障，仅表示该功能未在设置中开启；
- 绿（正常）：连接成功；
- 红（失败）：连接失败。
一个模型的状态不会改变另一个 chip 的颜色。将鼠标停在对应 chip 上可查看连接详情。关闭「显示模型状态」后，三枚 chip 隐藏且完全不发起检测请求（省 token）。
---
## 13. 数据与隐私
插件使用 uTools `dbStorage` 保存以下数据，不会把配置写入项目文件：
- `ai_config`：翻译模型配置；
- `ocr_llm_config`：OCR 模型配置；
- `tts_config`：朗读（TTS）模型配置；
- `app_config`：自动翻译、历史、默认语言、自动复制、划词查词、流式输出、同步滚动、模型状态、截图原文等应用配置；
- `translate_history`：翻译历史。
文本会发送到当前选中的翻译通道；图片会以 Base64 数据发送到已配置的 OCR 接口；译文朗读会发送到已配置的 TTS 服务。使用远程服务时，应根据所用服务的隐私政策决定是否提交敏感文本、图片或 API Key。
关闭「记录翻译历史」并保存会立即清空现有历史，插件界面不提供恢复功能。
---
## 14. 常见问题
### 主页模型状态为红色
主页顶部有 3 个独立 chip，分别并行检查「翻译 / OCR / 朗读」模型。连接正常的显示绿色，连接失败的显示红色，未启用对应功能（如未开朗读）的显示灰色「未启用」——灰色不等于故障，仅表示该功能未在设置中开启；一个模型的状态不会改变另一个芯片的颜色。将鼠标停在对应 chip 上可查看连接详情。
依次检查：
1. 本地模型服务是否已经启动；
2. 接口地址是否只填到 `/v1`；
3. 模型名称是否与服务返回的实际标识完全一致；
4. 自定义翻译的 API Key 是否非空；
5. OCR 模型是否支持 OpenAI 风格的图片输入；
6. 防火墙、代理或服务端日志是否显示请求失败。
### 地址出现重复的 `/chat/completions`
删除输入框中的 `/chat/completions`，只保留基础地址。例如把：
```text
http://127.0.0.1:54321/v1/chat/completions
```
改为：
```text
http://127.0.0.1:54321/v1
```
### OCR 没有返回文字
- 确认图片中存在清晰文字；
- 确认模型支持视觉输入，而不是纯文本模型；
- 将 Prompt 改为 `Free OCR.`；
- 将图片转成 PNG、JPEG 或 WebP 后重试；
- 如果提示超时，增大 OCR 超时时间；
- 查看开发者控制台中的 `[OCR LLM]` 日志，核对实际模型、请求地址、图片类型和大小。
### 修改代码或保存配置后看起来没有生效
- 设置页测试按钮不会保存配置，必须点击「保存配置」；
- uTools 会把开发插件打包为只读 asar。修改 `preload.js`、`preload/`、`plugin.json`，或遇到 HTML/CSS/JavaScript 缓存时，建议完全退出 uTools，再重新打开并载入插件；
- 配置只存在于 `dbStorage`，不要通过修改项目内 JSON 文件来尝试覆盖设置。
AI Translate 是一个 uTools 智能翻译插件，支持**文本翻译、图片 OCR 后翻译、文言文翻译、截图翻译、划词查词、译文朗读**，以及本地保存**翻译历史**。
插件本身没有构建步骤，也不是可直接在普通浏览器中运行的网页。运行时依赖 uTools 提供的插件入口、内置 AI、剪贴板和 `dbStorage` 能力。
---
## 1. 功能概览
| 功能 | 说明 |
| --- | --- |
| 文本翻译 | 手动输入、粘贴文本，或从 uTools 搜索框 / 划词传入文本 |
| 划词翻译 | 选中文字后通过 uTools「翻译选中」入口打开插件 |
| 图片翻译 | 读取剪贴板图片、图片文件，或在插件内粘贴 / 选择图片，经 OCR 识别后翻译 |
| 截图翻译 | 框选屏幕区域，主窗口隐藏，在选区处弹出透明浮窗原位显示原文与译文，可放大回主窗口继续编辑 |
| 文言文翻译 | 将文言文译为现代白话文（也可把外文译为文言文） |
| 译文朗读（TTS） | 朗读输入或译文，支持 OpenAI 兼容接口与火山引擎；关闭后主页不再显示朗读按钮 |
| 流式输出 | 自定义接口逐字显示译文；内置通道不支持时自动回退为整段返回 |
| 同步滚动 | 滚动左侧原文或右侧译文，另一侧按相同比例联动，始终对照同一段 |
| 富文本展示 | 自动识别 HTML 表格与 Markdown 并安全渲染，可切回原文 |
| 划词查词 | 选中待翻译区文字即弹卡片，给出释义与例句（可关闭） |
| 模型状态 | 主页顶部三枚独立 chip，分别检测翻译 / OCR / 朗读 的连通状态 |
| 翻译历史 | 可展开、复制、单条删除或清空，并可设置保留时长 |
| 方向自适应 | 阿拉伯语等 RTL 语言从右向左显示；蒙古语竖写 |
**两种翻译通道**：uTools 内置 AI，或自定义 OpenAI 兼容接口。
**OCR 识别**：调用支持图片输入的 OpenAI 兼容视觉模型，无 Tesseract 等本机 OCR 回退。
**支持的语言（16 种）**：简体中文、繁體中文、English、Français、Русский、日本語、한국어、Deutsch、Español、Português、Italiano、العربية（阿拉伯语）、ไทย、Tiếng Việt、文言文、蒙古语。源语言另支持「自动检测」（共 17 个选项）。其中文言文既可作源语言（古文今译）也可作目标语言（外文译文言）；阿拉伯语从右向左书写（RTL）；蒙古语为传统蒙文竖写。
---
## 2. 运行前准备
### 2.1 载入插件
1. 安装并打开 uTools。
2. 通过 uTools 开发者工具载入本项目的 `plugin.json`。
3. 在 uTools 中搜索或划词选「翻译」「翻译选中」「图片翻译」「翻译图片文件」、「截图翻译」「文言文翻译」「文言文翻译选中」进入插件。
项目是原生 HTML、CSS 和 JavaScript 结构，不需要执行 `npm install`、打包或构建。
> 不要直接双击 `index.html` 使用。普通浏览器中没有 `window.utools` 和预加载服务，翻译、OCR、朗读、复制及配置存储均无法正常工作。
### 2.2 模型要求
文本翻译至少需要以下一种能力：
- uTools 内置 AI；或
- 一个兼容 OpenAI `chat/completions` 请求格式的文本模型接口。
图片 OCR 必须另外配置一个兼容 OpenAI 多模态消息格式、且支持图片输入的视觉模型接口（例如本地运行的视觉语言模型服务）。即使只使用 uTools 内置翻译，图片识别仍需配置 OCR 模型。
译文朗读（TTS）需要配置一个 TTS 服务：
- OpenAI 兼容的语音合成接口（提供接口地址、API Key、模型与音色）；或
- 火山引擎语音合成（提供接口地址、API Key、资源 ID 与音色）。
---
## 3. 首次配置
点击主页右上角的齿轮进入设置。设置页从右侧滑出抽屉（不切换页面），按 **翻译模型 / OCR / 朗读 / 其他** 分为 4 个分组。测试按钮不写库，只有「保存配置」才持久化；切换 / 取消 / 退出均不写入 `dbStorage`。
### 3.1 翻译模型
#### uTools 内置
选择「uTools 内置」即可，无需填写接口地址、API Key 或模型名称。翻译请求通过 uTools 内置 AI 发出。
#### 自定义（仅 OpenAI 兼容）
| 字段 | 是否必填 | 说明 |
| --- | --- | --- |
| 接口地址 | 是 | 只填写基础地址，例如 `http://127.0.0.1:54321/v1` |
| API Key | 是 | 请求时以 `Authorization: Bearer ...` 发送 |
| 模型名称 | 是 | 填写服务实际暴露的模型标识 |
插件会自动在接口地址后追加 `/chat/completions`。**不要**填写完整的 `.../chat/completions` 地址，否则会得到重复后缀。
如果本地服务不校验鉴权，自定义翻译配置中仍需填写一个非空的 API Key 占位值，因为插件会校验该字段。
点击「测试连接」会用当前表单配置试译 `Hello`（使用正确的语言标识）。测试不会保存表单、修改现有配置，也不会写入翻译历史；只有「保存配置」才会持久化。
「模型名称」为「输入 + 下拉」组合框：点开后会自动向所填接口地址拉取可用模型列表（同一地址只拉一次），也可手动输入列表中没有的模型标识。
### 3.2 OCR 识别配置
| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| 接口地址 | `http://localhost:11434/v1` | 只填写基础地址，插件自动追加 `/chat/completions` |
| 模型名称 | 空 | 必须是支持图片输入的视觉模型 |
| API Key | 空 | 可选；本地无鉴权服务通常留空 |
| 超时时间 | `60000` ms | 模型较慢时可适当增大（范围 1000–600000） |
| Prompt | `Free OCR.` | 发给视觉模型的识别提示词 |
点击「测试 OCR」后，插件会生成一张包含 `AI Translate 测试 OCR 123` 的测试图，并使用当前表单配置识别。测试同样不会保存配置。
DeepSeek-OCR 系列对提示词较敏感。如果出现无识别内容、`completion_tokens=0` 或模型拒答，优先把 Prompt 恢复为简短英文 `Free OCR.`。
### 3.3 朗读（TTS）配置
- **服务开关**：关闭时插件不显示朗读按钮。
- **服务类型**：OpenAI 兼容 或 火山引擎，二者择一。
- **OpenAI 兼容**：填写接口地址、API Key、模型与音色（voice）。
- **火山引擎**：填写接口地址、API Key、资源 ID 与音色。
- 「音色 voice」为组合框：OpenAI 兼容模式点开后会自动拉取可用音色列表（需先填模型），火山引擎则手动填写发音人标识（如 `zh_female_qingxin`）。
- 关闭翻译窗口会自动停止正在进行的朗读，临时音频也会释放。
### 3.4 其他配置
**翻译行为**
- **自动翻译**：默认开启。开启后，文本进入待翻译区即翻译（受下方防抖控制）；关闭时清空结果，改用两个文本框中间的「译」按钮手动翻译。切换内置 / 自定义模式不会清空已填配置。
- **自动翻译防抖（毫秒）**：仅在自动翻译开启时可用，控制输入停顿多久才发起翻译（默认 500，范围 0–5000，0 即即时翻译）。可避免逐字输入时每次按键都调用模型；按量计费接口可保留防抖以省 token。
- **翻译后自动复制结果**：默认关闭。开启后译文自动写入剪贴板（与手动「复制」等价）。
- **划词查词**：默认开启。关闭后选中待翻译区文字不再弹出查词卡片。
- **流式输出译文**：默认开启。自定义接口下译文逐字显示；内置 utools.ai 不支持流式时自动回退为整段返回。
**默认语言**
- **默认源语言 / 默认目标语言**：新开页面时预选的语言，可设为「自动检测」或具体语言。目标语言设为「自动」（自动检测）时跟随系统语言（依 uTools 语言判断简体 / 繁体中文）。
**历史记录**
- **历史记录**：默认开启。关闭并保存后，会立即清空已有历史、停止继续记录，并隐藏主页历史面板。
- **历史保留时长**：可选不限、最近 1 小时、1 天、1 周或 1 月；无论选择哪一项，最多保存 100 条。
**主页面状态与交互**
- **显示模型状态**：默认开启。关闭后主页不再显示「翻译 / OCR / 朗读」三个连通性 chip，也不再发起任何连通性检测（省 token）。
- **同步滚动原文与译文**：默认开启。开启后，滚动一侧，另一侧按相同比例联动，始终对照同一段内容。
**截图翻译**
- **截图后浮窗显示原文**：默认开启。截图翻译浮窗在译文之外是否同时显示 OCR 识别的原文；关闭则仅显示译文。
- 该分组内另含三条使用提示：OCR 依赖、快捷键绑定指引、macOS 屏幕录制权限。
完成设置后点击「保存配置」。「取消」会放弃本次表单修改。
---
## 4. 文本翻译
### 4.1 在插件内翻译
1. 选择源语言；不确定时保留「自动检测」。
2. 选择目标语言，默认为「自动」（跟随系统语言）。
3. 在左侧待翻译区输入或粘贴文本。
4. 自动翻译开启时会立即翻译（受防抖控制）；关闭时点击两个文本框中间圆形的「译」按钮。
5. 点击右侧「复制」复制译文；若开启了自动复制，译文会直接进剪贴板。
6. 点击朗读按钮，可把译文（或原文）朗读出来。
**流式输出**：自定义接口下，译文会逐字显示，无需等待整段返回；内置通道不支持流式时自动整段返回。
**同步滚动**：开启后滚动任意一侧文本框，另一侧按相同比例联动，方便长文本逐段对照。
**交换语言**：源语言为「自动检测」时，交换按钮不可用；选择具体源语言后，点击交换按钮会同时交换源语言、目标语言、原文和译文。
### 4.2 从 uTools 调用
- **文本入口**：在 uTools 搜索框中输入或粘贴文本，选择「翻译」。
- **划词入口**：选中文字后，从 uTools 超级面板进入「翻译选中」。
- **文言文入口**：在 uTools 搜索框输入文言文，选择「文言文翻译」；或划词选「文言文翻译选中」。
插件重复进入同一个翻译页面时会保留当前输入、结果和语言选择，不会主动重置页面状态。
---
## 5. 图片 OCR 与翻译
可以通过以下方式识别图片：
- 在 uTools 中复制图片后选择「图片翻译」；
- 在 uTools 中传入图片文件后选择「图片翻译」；
- 在插件主页点击「图片」，再点击「选择图片」；
- 在左侧输入区、表格视图或图片面板获得焦点后，按 `Ctrl+V` / `Command+V` 粘贴图片。
识别流程为：读取图片 → 调用 OCR 视觉模型 → 将识别文字填入左侧 → 按「自动翻译」设置决定是否继续翻译。
一次通过 uTools 文件入口传入多张图片时，当前版本只处理第一张。
`plugin.json` 目前声明支持 PNG、JPG/JPEG、GIF 和 WebP 文件入口；OCR 服务层能可靠识别的 MIME 类型也是这几种。遇到其它格式时，优先转换为 PNG、JPEG 或 WebP 后再试。
---
## 6. 截图翻译
截图翻译让你在屏幕上框选一块区域，插件在选区位置原位弹出透明浮窗显示识别出的原文与译文，不打断当前工作；需要细看或继续编辑时，可一键放大回主窗口。
### 6.1 如何触发
- 主页语言栏右侧的「截图」按钮（需先在 OCR 配置中开启本地 OCR 模型；未开启时该按钮自动隐藏）；
- 在 uTools 中通过全局快捷键调用「截图翻译」（在 uTools 菜单「设置 → 快捷键 → 插件」里为「截图翻译」命令绑定组合键，插件本身无法在代码内注册系统热键）。
### 6.2 工作流程
1. 点击「截图」或触发快捷键后，主窗口立即隐藏，整个识别翻译过程主窗口都不露面；
2. 框选屏幕区域，松手那一刻在光标处弹出「识别翻译中…」加载浮窗（即时反馈，无需干等）；
3. 后台并行完成 OCR 识别与翻译，结果算好后在同一位置弹出结果浮窗；
4. 结果浮窗关闭时主窗口保持隐藏；只有点击「放大」回到主窗口时，才会重新显示主窗口并回填截图、原文、译文。
### 6.3 浮窗操作
结果浮窗为透明无边框窗口，大小贴合选区内容、可手动拖拽边缘缩放：
- 左上「放大」图标：把截图、原文、译文回填到主窗口并重新显示主窗口（不退出插件）；
- 右上「X」/ 按 `Esc` / 点击浮窗外的透明区域：直接退出插件，主窗口保持关闭；
- 「复制译文」「复制原文」按钮：仅在 OCR 开启时显示（OCR 关闭则截图翻译无产出），点击后按钮短暂变为「已复制」；
- 译文同样支持表格 / Markdown 富文本渲染（与主页一致）；原文与译文的显示方向也会随语言自动适配（见第 9 节）。
> 浮窗关闭或退出后，主窗口不会自动弹出；若想回到主窗口查看或编辑，请使用左上「放大」图标。
### 6.4 相关设置
- 「截图后浮窗显示原文」（其他配置）：默认开启，浮窗在译文之外同时显示 OCR 原文；关闭则只显示译文。
- 截图翻译同样遵循「翻译后自动复制结果」设置：若开启，译文会直接写入剪贴板。
### 6.5 依赖与权限
截图翻译依赖本地 OCR 视觉模型，且 macOS 首次使用会请求「屏幕录制」权限（设置路径：系统设置 → 隐私与安全性 → 屏幕录制，勾选 uTools 后完全退出重开）。若截取为黑屏，请检查该权限是否已授予。
---
## 7. 文言文翻译
通过「文言文翻译」入口，将文言文译为现代白话文；选择具体目标语言为「文言文」时，也可把外文译为文言文。其余输入、翻译、复制、朗读、历史行为与文本翻译一致。
---
## 8. 表格与富文本
当待翻译文本或翻译结果中包含有效的 HTML 表格结构，例如 `
| ... |
- 点击「查看原文」可查看模型返回的原始文本；
- 点击「查看表格」可切回表格视图；
- 表格会经过白名单重建，仅保留表格行、单元格、合并行列和纯文本，不会直接执行模型返回的 HTML 或脚本。
如果模型返回的标签不完整且无法形成有效单元格，插件会降级为普通文本展示。
除了 HTML 表格，待翻译区和结果区还会渲染 Markdown 语法（标题、列表、引用、代码块、分隔线、GFM 表格）。当内容被识别为富文本时，底栏会显示「已识别为表格」或「已识别为 Markdown」，点击「查看原文」可查看模型返回的原始文本。所有富文本都经过白名单重建，只保留安全标签，不会直接执行模型返回的 HTML 或脚本。
---
## 9. 语言方向与排版
插件会根据所选语言自动调整文字方向，无需手动设置：
- **RTL（从右向左）**：阿拉伯语（العربية）的原文 / 译文以从右向左书写与排版，输入框与结果区方向自动适配。
- **竖写**：蒙古语（蒙古语）使用传统蒙文竖排（字从上到下、列从左到右）；仅结果展示区生效，输入框保持横排。
- **系统语言匹配**：目标语言设为「自动检测」时，依 uTools 语言判断简体 / 繁体中文；其它语言按系统区域语言自动匹配（文言文、蒙古语不参与系统自动匹配）。
---
## 10. 划词查词
划词查词仅在待翻译区生效（结果区整体关闭）。选中文字即弹出浮动卡片，给出单词释义与例句（可在设置中关闭）。选中文本长度上限 200 字，选词后会有约 500ms 的稳定窗口再触发查词，避免拖动过程中频繁请求。
查词 prompt 要求模型返回纯 JSON（无例句解释前缀），渲染层仅做空值过滤、查询词高亮与字符串数组兼容，正确性由 prompt 保证。
---
## 11. 翻译历史
主页底部的「翻译历史」默认收起，点击横条展开：
- 点击一条记录：复制该条译文；
- 点击记录右侧的 `×`：删除该条记录；
- 点击「清空」，再点击「确认清空？」：清空全部记录；
- 按 `Esc`：收起历史面板。
连续自动翻译时，2 分钟内、源语言和目标语言都相同且原文互为前缀的输入会合并为一条记录，避免逐字输入产生大量中间历史。完全相同的记录会移动到最前并刷新时间。历史最多保存 100 条，保留时长可在「其他配置」中设置。
---
## 12. 模型状态
主页顶部有 3 个独立 chip，分别检测「翻译 / OCR / 朗读」模型的连通状态，各自独立显示：
- 灰（检测中 / 未启用）：功能未开启（如未开朗读）时显示「未启用」——灰色不等于故障，仅表示该功能未在设置中开启；
- 绿（正常）：连接成功；
- 红（失败）：连接失败。
一个模型的状态不会改变另一个 chip 的颜色。将鼠标停在对应 chip 上可查看连接详情。关闭「显示模型状态」后，三枚 chip 隐藏且完全不发起检测请求（省 token）。
---
## 13. 数据与隐私
插件使用 uTools `dbStorage` 保存以下数据，不会把配置写入项目文件：
- `ai_config`：翻译模型配置；
- `ocr_llm_config`：OCR 模型配置；
- `tts_config`：朗读（TTS）模型配置；
- `app_config`：自动翻译、历史、默认语言、自动复制、划词查词、流式输出、同步滚动、模型状态、截图原文等应用配置；
- `translate_history`：翻译历史。
文本会发送到当前选中的翻译通道；图片会以 Base64 数据发送到已配置的 OCR 接口；译文朗读会发送到已配置的 TTS 服务。使用远程服务时，应根据所用服务的隐私政策决定是否提交敏感文本、图片或 API Key。
关闭「记录翻译历史」并保存会立即清空现有历史，插件界面不提供恢复功能。
---
## 14. 常见问题
### 主页模型状态为红色
主页顶部有 3 个独立 chip，分别并行检查「翻译 / OCR / 朗读」模型。连接正常的显示绿色，连接失败的显示红色，未启用对应功能（如未开朗读）的显示灰色「未启用」——灰色不等于故障，仅表示该功能未在设置中开启；一个模型的状态不会改变另一个芯片的颜色。将鼠标停在对应 chip 上可查看连接详情。
依次检查：
1. 本地模型服务是否已经启动；
2. 接口地址是否只填到 `/v1`；
3. 模型名称是否与服务返回的实际标识完全一致；
4. 自定义翻译的 API Key 是否非空；
5. OCR 模型是否支持 OpenAI 风格的图片输入；
6. 防火墙、代理或服务端日志是否显示请求失败。
### 地址出现重复的 `/chat/completions`
删除输入框中的 `/chat/completions`，只保留基础地址。例如把：
```text
http://127.0.0.1:54321/v1/chat/completions
```
改为：
```text
http://127.0.0.1:54321/v1
```
### OCR 没有返回文字
- 确认图片中存在清晰文字；
- 确认模型支持视觉输入，而不是纯文本模型；
- 将 Prompt 改为 `Free OCR.`；
- 将图片转成 PNG、JPEG 或 WebP 后重试；
- 如果提示超时，增大 OCR 超时时间；
- 查看开发者控制台中的 `[OCR LLM]` 日志，核对实际模型、请求地址、图片类型和大小。
### 修改代码或保存配置后看起来没有生效
- 设置页测试按钮不会保存配置，必须点击「保存配置」；
- uTools 会把开发插件打包为只读 asar。修改 `preload.js`、`preload/`、`plugin.json`，或遇到 HTML/CSS/JavaScript 缓存时，建议完全退出 uTools，再重新打开并载入插件；
- 配置只存在于 `dbStorage`，不要通过修改项目内 JSON 文件来尝试覆盖设置。