DOCUMENTATION · V1.2.8

使用文档

从安装、授权到划词、OCR、网页与文档翻译。这里是划词翻译的完整使用说明。

适用于 macOS / Windows / Linux更新于 2026.11

安装与升级

安装脚本会自动识别操作系统与 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,按系统下载对应文件:

平台推荐文件说明
macOSSelectionTranslator-<版本>-mac-<架构>.dmg安装到「应用程序」;Apple Silicon 与 Intel 分开下载
Windows 10/11SelectionTranslator-<版本>-Setup-<架构>.exex64 与 arm64;运行安装向导
Windows 7 SP1 x64SelectionTranslator-<版本>-Setup-win7-x64.exe兼容包,仅支持 64 位,需手动更新
LinuxSelectionTranslator-<版本>-<架构>.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 通常无需额外授权。

  1. 打开系统设置进入「隐私与安全性 → 辅助功能」。
  2. 添加并勾选「划词翻译」开发模式下需要添加并勾选 Electron。
  3. 完全退出后重新启动仅关闭窗口通常不够;请从菜单栏退出应用后重新打开。
  4. 重新选中文字测试如果仍未出现按钮,请检查触发方式与目标应用是否支持复制。
取词原理

macOS 优先通过 AXSelectedText 读取选区;Windows 优先通过 UI Automation TextPattern;Linux 读取主选区。只有原生直读不可用或为空时,才回退到受控的复制流程。

快速开始

默认模式是「选区按钮」:选中文字后,选区附近会出现「译」按钮,点击后显示译文。

01

选中文字

在浏览器、Office、PDF、聊天软件或 IDE 中选择文字。

02

点击「译」

也可以改用自动翻译,或按全局快捷键 Alt + T。

03

查看译文

在弹窗中朗读、复制、固定,或临时切换语言与翻译通道。

macOS 上 Alt 对应 Option(⌥),默认快捷键是 ⌥T。快捷键可在设置中修改,但应用会拒绝注册 Command+C / Ctrl+C 等系统复制组合,避免干扰正常复制。

划词翻译

三种触发方式

方式行为适合
选区按钮(默认)选中文字后显示「译」按钮,点击才翻译希望翻译完全由自己控制
自动翻译完成选词后直接打开弹窗并翻译高频阅读外文资料
仅快捷键划词不自动响应,只通过全局快捷键触发不希望选区旁出现按钮

弹窗操作

  • 手动翻译:点击文档图标,在划词翻译与手动输入之间切换。
  • 朗读:点击扬声器朗读当前译文,再次点击停止。默认使用系统内置语音,不会自动播放。
  • 图钉:固定弹窗,避免点击外部或自动隐藏计时导致关闭。
  • 复制:将当前译文写入系统剪贴板。
  • 语言选择器:临时修改源语言和目标语言并重新翻译。
  • 关闭:点击「×」或按 Esc。

手动翻译

点击弹窗左上角的文档图标,或从菜单栏/托盘选择「手动翻译…」。在输入框中粘贴或输入文本,按 Enter 提交;Shift + Enter 换行。

截图 OCR

图片、扫描 PDF、视频字幕或游戏界面无法直接复制时,用框选 OCR 识别文字,再送入翻译通道。

截图识别流程

  1. 按下 Alt + O默认截图快捷键,也可从菜单栏/托盘的「截图 OCR 翻译…」进入。
  2. 拖拽绘制选区可拖动整体,或用八个控制点调整大小。
  3. 识别文字点击「识别文字」,结果显示在选区侧栏,可调整侧栏尺寸。
  4. 翻译结果点击「翻译」,把识别文字送入当前翻译通道。

按 Esc 或点击取消退出框选。剪贴板中有图片时,也可以从托盘选择「剪贴板图片 OCR 翻译…」,直接识别并翻译。

OCR 引擎

自动模式按「系统 OCR → PaddleOCR → Tesseract」回退。macOS 使用 Vision,Windows 使用系统 OCR;PaddleOCR 使用随包分发的 PP-OCRv6 ONNX 模型;Tesseract 作为最后的本地兜底。

图片不会上传

截图与剪贴板图片在本机完成 OCR。只有识别出的文字会按当前翻译通道发送给对应服务。

标注与导出

截图工具栏支持矩形、椭圆、箭头、画笔、文字、马赛克、高亮、高斯模糊、聚光灯、撤销/重做和清空标注。完成后可复制图片到剪贴板,或保存为 PNG。

网页全文翻译

内置网页阅读器把译文写回原文位置,不创建侧栏,也不重建页面结构。

  1. 打开网页翻译从菜单栏/托盘的「打开网页翻译…」或翻译弹窗入口进入。
  2. 输入地址并选择语言源语言默认自动检测,目标语言可选择固定语言或自动中英互译。
  3. 点击「翻译此页」只有显式点击后才读取当前主文档的可见内容。
  4. 切换显示模式支持原文、译文与对照模式;也可以对页面图片执行 OCR 后翻译。

提取与隐私边界

  • 不读取 Chrome、Edge、Safari、Firefox 等系统浏览器已打开的标签页。
  • 只读取当前主文档中已经渲染且可见的 DOM,不跨 iframe,不穿透 Shadow DOM。
  • 提取脚本只读;受控写回脚本只修改锚点匹配的文本节点,不改变 DOM 结构。
  • 动态页面变化只提示重新翻译,不会自动提取或上传新增内容。

文档翻译工作台

一次导入一个本地文件,完成解析、OCR、翻译、左右对照和 PDF 导出。

文档格式PDF · DOCX · EPUB · HTML · Markdown · TXT · JSON · CSV · SRT · VTT
图片格式PNG · JPG / JPEG · WebP · GIF · BMP

翻译与版式

文档存在原生文本层时优先使用;扫描版 PDF 会先栅格化再 OCR。公式作为不可翻译区块保留,表格、图片、分栏与样式会在源格式提供信息时尽量重建。复杂矢量、艺术字、跨页表格和竖排文本可能产生版式告警。

导出模式

模式结果
保留版式译文 PDF尽量保留页面尺寸、区块位置、字体、表格、图片和公式
左右双语 PDF左侧原文、右侧译文;固定版式 PDF 使用原页或缩略图作为原文侧

若仍有翻译失败区块,可重试未完成块,或在显式确认后导出部分结果。部分导出会保留全部页面,失败区块保留原文并添加标记。

Windows 7 不支持文档翻译

Win7 兼容包会显示不支持提示。划词、截图 OCR 与网页翻译仍按各自平台能力可用。

翻译通道

默认按优先级尝试可用通道。当前通道失败或熔断时,会自动切换到后续通道。

优先级通道启用条件
1AI 翻译已启用,协议 / Base URL / 模型配置完整
2钉钉翻译已启用,企业应用配置完整
3微软翻译已启用,语言对受支持
4自建 DeepLX已填写 /translate 服务地址
5公共 DeepLX默认兜底,可能限流
6Google当前网络可访问 Google 翻译接口
7MyMemory前面通道均失败

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 + TElectron accelerator 格式
结果自动隐藏不自动隐藏0 / 3 / 5 / 8 / 15 秒
语音引擎系统内置语音可切换 Edge 在线神经网络语音

配置文件位置

公开设置保存在 Electron 的 userData 目录。macOS 打包应用通常位于 ~/Library/Application Support/划词翻译/settings.json。AI Key、钉钉 Secret 与日志分别使用独立文件或目录,不会写入公开设置。

修改设置文件前请先退出应用,并建议备份原文件。不同版本会通过 schemaVersion 自动迁移。

语音

默认系统内置语音不会产生新的应用侧网络请求。主动启用 Edge 在线语音后,朗读会联网,并把当前译文发送给微软在线朗读服务;失败时自动回退系统语音。

隐私与安全

划词翻译不提供云端账户系统。应用只在明确触发后读取内容,并把必要的文字发送给你选择的翻译服务。

本机 OCR

截图、页面截图、文档内嵌图片和公式裁剪图在本机处理,图片字节不上传。

加密凭证

AI API Key 与钉钉 Secret 使用系统安全存储加密,不写入公开设置或日志。

显式授权

网页只在点击「翻译此页」后提取;文档只读取你主动选择或拖入的文件。

最小数据流

只有进入翻译范围的文字会发送到当前翻译通道,翻译结果在本地弹窗显示。

数据流

  1. 读取选区或识别文字优先本机直读或本地 OCR。
  2. 发送必要文字根据当前通道发送给对应翻译服务;若配置本地模型或自建服务,可留在本机或内网。
  3. 返回译文在本地弹窗、网页或文档工作台显示,由你决定是否复制或导出。

不建议直接翻译密码、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 元数据;非固定路径安装、未签名或签名不匹配构建会降级为手动安装。
  • 项目暂不提供账号体系和云端同步。