DOCUMENTATION · V1.2.8
使用文档
从安装、授权到划词、OCR、网页与文档翻译。这里是划词翻译的完整使用说明。
安装与升级
安装脚本会自动识别操作系统与 CPU 架构,从 GitHub Releases 下载对应安装包、校验 SHA-256,并安装到当前用户目录。也可以在 Releases 页面手动下载。
脚本不要求管理员权限。macOS 默认安装到 ~/Applications;Linux 安装 AppImage 到 ~/.local/bin;Windows 会运行 NSIS 安装向导。
curl -fsSL https://raw.githubusercontent.com/zhq734/translation/master/scripts/install.sh | sh手动下载
打开 GitHub Releases,按系统下载对应文件:
| 平台 | 推荐文件 | 说明 |
|---|---|---|
| macOS | SelectionTranslator-<版本>-mac-<架构>.dmg | 安装到「应用程序」;Apple Silicon 与 Intel 分开下载 |
| Windows 10/11 | SelectionTranslator-<版本>-Setup-<架构>.exe | x64 与 arm64;运行安装向导 |
| Windows 7 SP1 x64 | SelectionTranslator-<版本>-Setup-win7-x64.exe | 兼容包,仅支持 64 位,需手动更新 |
| Linux | SelectionTranslator-<版本>-<架构>.AppImage | 赋予执行权限后运行;x64 / arm64 |
所有安装包应与同一 Release 中的 SHA256SUMS 一起使用。应用内检查更新会读取 Release 元数据,但不会未经确认自动下载和安装。
macOS 自动升级
应用内自动升级仅适用于固定路径 /Applications/划词翻译.app。从 DMG、下载目录或其他位置运行时,更新会降级为手动安装。通过一键脚本安装到 ~/Applications 时,如需自动升级,请先将应用移动到 /Applications。
Windows 7 说明
Win7 包使用 Electron 22 兼容运行时,该运行时已停止安全更新。文档翻译不可用;OCR 固定使用 Tesseract.js WebAssembly,内置简体中文、繁体中文与英文模型。应用内更新只打开 Release 页面,不会自动下载安装。
首次授权
macOS 需要「辅助功能」权限,才能读取其他应用中的选中文字。Windows 与 Linux 通常无需额外授权。
- 打开系统设置进入「隐私与安全性 → 辅助功能」。
- 添加并勾选「划词翻译」开发模式下需要添加并勾选
Electron。 - 完全退出后重新启动仅关闭窗口通常不够;请从菜单栏退出应用后重新打开。
- 重新选中文字测试如果仍未出现按钮,请检查触发方式与目标应用是否支持复制。
macOS 优先通过 AXSelectedText 读取选区;Windows 优先通过 UI Automation TextPattern;Linux 读取主选区。只有原生直读不可用或为空时,才回退到受控的复制流程。
快速开始
默认模式是「选区按钮」:选中文字后,选区附近会出现「译」按钮,点击后显示译文。
选中文字
在浏览器、Office、PDF、聊天软件或 IDE 中选择文字。
点击「译」
也可以改用自动翻译,或按全局快捷键 Alt + T。
查看译文
在弹窗中朗读、复制、固定,或临时切换语言与翻译通道。
macOS 上 Alt 对应 Option(⌥),默认快捷键是 ⌥T。快捷键可在设置中修改,但应用会拒绝注册 Command+C / Ctrl+C 等系统复制组合,避免干扰正常复制。
划词翻译
三种触发方式
| 方式 | 行为 | 适合 |
|---|---|---|
| 选区按钮(默认) | 选中文字后显示「译」按钮,点击才翻译 | 希望翻译完全由自己控制 |
| 自动翻译 | 完成选词后直接打开弹窗并翻译 | 高频阅读外文资料 |
| 仅快捷键 | 划词不自动响应,只通过全局快捷键触发 | 不希望选区旁出现按钮 |
弹窗操作
- 手动翻译:点击文档图标,在划词翻译与手动输入之间切换。
- 朗读:点击扬声器朗读当前译文,再次点击停止。默认使用系统内置语音,不会自动播放。
- 图钉:固定弹窗,避免点击外部或自动隐藏计时导致关闭。
- 复制:将当前译文写入系统剪贴板。
- 语言选择器:临时修改源语言和目标语言并重新翻译。
- 关闭:点击「×」或按 Esc。
手动翻译
点击弹窗左上角的文档图标,或从菜单栏/托盘选择「手动翻译…」。在输入框中粘贴或输入文本,按 Enter 提交;Shift + Enter 换行。
截图 OCR
图片、扫描 PDF、视频字幕或游戏界面无法直接复制时,用框选 OCR 识别文字,再送入翻译通道。
截图识别流程
- 按下 Alt + O默认截图快捷键,也可从菜单栏/托盘的「截图 OCR 翻译…」进入。
- 拖拽绘制选区可拖动整体,或用八个控制点调整大小。
- 识别文字点击「识别文字」,结果显示在选区侧栏,可调整侧栏尺寸。
- 翻译结果点击「翻译」,把识别文字送入当前翻译通道。
按 Esc 或点击取消退出框选。剪贴板中有图片时,也可以从托盘选择「剪贴板图片 OCR 翻译…」,直接识别并翻译。
OCR 引擎
自动模式按「系统 OCR → PaddleOCR → Tesseract」回退。macOS 使用 Vision,Windows 使用系统 OCR;PaddleOCR 使用随包分发的 PP-OCRv6 ONNX 模型;Tesseract 作为最后的本地兜底。
截图与剪贴板图片在本机完成 OCR。只有识别出的文字会按当前翻译通道发送给对应服务。
标注与导出
截图工具栏支持矩形、椭圆、箭头、画笔、文字、马赛克、高亮、高斯模糊、聚光灯、撤销/重做和清空标注。完成后可复制图片到剪贴板,或保存为 PNG。
网页全文翻译
内置网页阅读器把译文写回原文位置,不创建侧栏,也不重建页面结构。
- 打开网页翻译从菜单栏/托盘的「打开网页翻译…」或翻译弹窗入口进入。
- 输入地址并选择语言源语言默认自动检测,目标语言可选择固定语言或自动中英互译。
- 点击「翻译此页」只有显式点击后才读取当前主文档的可见内容。
- 切换显示模式支持原文、译文与对照模式;也可以对页面图片执行 OCR 后翻译。
提取与隐私边界
- 不读取 Chrome、Edge、Safari、Firefox 等系统浏览器已打开的标签页。
- 只读取当前主文档中已经渲染且可见的 DOM,不跨 iframe,不穿透 Shadow DOM。
- 提取脚本只读;受控写回脚本只修改锚点匹配的文本节点,不改变 DOM 结构。
- 动态页面变化只提示重新翻译,不会自动提取或上传新增内容。
文档翻译工作台
一次导入一个本地文件,完成解析、OCR、翻译、左右对照和 PDF 导出。
翻译与版式
文档存在原生文本层时优先使用;扫描版 PDF 会先栅格化再 OCR。公式作为不可翻译区块保留,表格、图片、分栏与样式会在源格式提供信息时尽量重建。复杂矢量、艺术字、跨页表格和竖排文本可能产生版式告警。
导出模式
| 模式 | 结果 |
|---|---|
| 保留版式译文 PDF | 尽量保留页面尺寸、区块位置、字体、表格、图片和公式 |
| 左右双语 PDF | 左侧原文、右侧译文;固定版式 PDF 使用原页或缩略图作为原文侧 |
若仍有翻译失败区块,可重试未完成块,或在显式确认后导出部分结果。部分导出会保留全部页面,失败区块保留原文并添加标记。
Win7 兼容包会显示不支持提示。划词、截图 OCR 与网页翻译仍按各自平台能力可用。
翻译通道
默认按优先级尝试可用通道。当前通道失败或熔断时,会自动切换到后续通道。
| 优先级 | 通道 | 启用条件 |
|---|---|---|
| 1 | AI 翻译 | 已启用,协议 / Base URL / 模型配置完整 |
| 2 | 钉钉翻译 | 已启用,企业应用配置完整 |
| 3 | 微软翻译 | 已启用,语言对受支持 |
| 4 | 自建 DeepLX | 已填写 /translate 服务地址 |
| 5 | 公共 DeepLX | 默认兜底,可能限流 |
| 6 | 当前网络可访问 Google 翻译接口 | |
| 7 | MyMemory | 前面通道均失败 |
AI 翻译
支持 Ollama、OpenAI 兼容与 Claude Code(Anthropic)兼容三种 HTTP 协议。可在线检测端点、自动拉取模型列表。API Key 使用 safeStorage 加密后写入独立的 ai-credentials.json,不会写入公开设置或日志。
自建 DeepLX
在设置中填写完整的 /translate 服务地址,并可在线检测。使用 Docker 部署时,确保端口未被占用;代理模式为系统或自定义代理时,绕过规则应保留 localhost、127.0.0.1 和 <local>。
钉钉企业翻译
在钉钉开放平台创建企业内部应用并开通「AI 文本翻译」权限,准备 CorpId、ClientId 与 ClientSecret。Secret 只通过设置页提交给主进程,使用 safeStorage 加密保存。
微软翻译
无需 Azure 账号、订阅密钥或 Region。应用会先加载 Bing 翻译页面并提取短期参数,再请求网页翻译接口。临时参数只缓存在内存中,不写入凭证文件。该能力使用非官方接口,可能随 Bing 页面结构或反滥用策略调整而失效。
设置与外观
常用设置
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 界面语言 | 跟随系统 | 简体中文、English 或跟随系统 |
| 主题模式 | 跟随系统 | 跟随系统、始终浅色、始终深色 |
| 主题配色 | 天空蓝 | 樱花粉、祖母绿、天空蓝、藏青、铂金黑 |
| 目标语言 | 自动中英互译 | 也可选择固定目标语言 |
| 源语言 | 自动检测 | 也可选择固定源语言 |
| 触发方式 | 选区按钮 | 自动翻译、选区按钮、仅快捷键 |
| 全局快捷键 | Alt + T | Electron accelerator 格式 |
| 结果自动隐藏 | 不自动隐藏 | 0 / 3 / 5 / 8 / 15 秒 |
| 语音引擎 | 系统内置语音 | 可切换 Edge 在线神经网络语音 |
配置文件位置
公开设置保存在 Electron 的 userData 目录。macOS 打包应用通常位于 ~/Library/Application Support/划词翻译/settings.json。AI Key、钉钉 Secret 与日志分别使用独立文件或目录,不会写入公开设置。
修改设置文件前请先退出应用,并建议备份原文件。不同版本会通过 schemaVersion 自动迁移。
语音
默认系统内置语音不会产生新的应用侧网络请求。主动启用 Edge 在线语音后,朗读会联网,并把当前译文发送给微软在线朗读服务;失败时自动回退系统语音。
隐私与安全
划词翻译不提供云端账户系统。应用只在明确触发后读取内容,并把必要的文字发送给你选择的翻译服务。
截图、页面截图、文档内嵌图片和公式裁剪图在本机处理,图片字节不上传。
AI API Key 与钉钉 Secret 使用系统安全存储加密,不写入公开设置或日志。
网页只在点击「翻译此页」后提取;文档只读取你主动选择或拖入的文件。
只有进入翻译范围的文字会发送到当前翻译通道,翻译结果在本地弹窗显示。
数据流
- 读取选区或识别文字优先本机直读或本地 OCR。
- 发送必要文字根据当前通道发送给对应翻译服务;若配置本地模型或自建服务,可留在本机或内网。
- 返回译文在本地弹窗、网页或文档工作台显示,由你决定是否复制或导出。
不建议直接翻译密码、API Key、客户隐私、未公开源代码或其他敏感内容。使用第三方翻译服务时,请自行评估其隐私政策、数据保留、配额与服务条款。
微软网页翻译、公共 DeepLX、Google、MyMemory 与 Edge 在线语音均依赖第三方接口。它们可能限流、变更或停止工作,也可能按各自政策处理请求内容。
常见问题
划词后没有按钮或译文+
确认已授予 macOS 辅助功能权限;确认触发方式不是「仅使用快捷键」;如果是快捷键模式,请按已配置的组合;完全退出旧进程后重新启动。某些应用使用自绘控件或不支持系统复制,无法通过当前机制取词。
翻译失败或出现 429+
公共 DeepLX 可能被限流,Google 可能受网络环境影响。应用会自动尝试后续通道;如果仍不稳定,建议配置自建 DeepLX,并确认服务地址、端口与代理绕过规则。
macOS 提示「应用已损坏,无法打开」+
先确认安装包来源可信,并确认它是否为未签名构建。未签名包首次打开时,可在确认来源后执行:xattr -dr com.apple.quarantine "/Applications/划词翻译.app",然后重新打开应用。若需减少 Gatekeeper 提示并启用自动升级,应使用签名公证包。
钉钉 Secret 保存失败+
Electron safeStorage 不可用时,应用会拒绝写入明文凭证。请确认系统钥匙串/安全存储可用,重新启动应用后再试;不要手动把 Secret 写入 settings.json。
微软翻译检测失败+
该通道不需要 Azure 密钥或 Region。确认当前网络和代理可以访问 www.bing.com;如果 Bing 拒绝临时网页会话或触发限流,请稍后重试,并保留后续兜底通道。
npm install 失败+
确认 Node.js 版本不低于 18;删除不完整依赖后重新安装。原生模块编译错误请安装 Xcode Command Line Tools,并确认 Node/Electron 架构匹配。npm 缓存权限异常时可临时使用项目内缓存:npm install --cache ./.npm-cache。
已知限制
- macOS 是当前主要验证平台;Windows 与 Linux 的全局划词、权限和快捷键仍建议在真实目标设备上验证。
- 取词依赖系统选区能力,不保证兼容所有自绘文本控件、远程桌面或受限应用。
- 单次输入最长处理 5000 个字符;部分兜底通道有更短限制。
- 文档工作台一次处理一个文件;批量翻译与 PPTX / XLSX 不在当前版本范围。
- Windows 7 兼容包使用已停止安全更新的 Electron 22,且不支持文档翻译。
- 自动更新依赖 GitHub Release 元数据;非固定路径安装、未签名或签名不匹配构建会降级为手动安装。
- 项目暂不提供账号体系和云端同步。