把鼠标侧键变成朗读按钮：选中文字就能听，英文内容顺手看中文翻译，不能复制的文字也能截图识别。
这是一个运行在 Windows 上的 Python 小工具，使用微软「晓晓」语音朗读，通过微软 Translator API 显示中文译文，通过本地 OCR 识别屏幕文字。适合浏览英文网页、查单词、阅读文档，以及听读中文内容。
本项目的最佳搭配是 G502 这类多按键可编程鼠标。 将三个功能分配给顺手的侧键后，指向、选中、朗读和截图都可以用鼠标完成。普通鼠标也能使用，推荐改用 F8 / F9 / F10。
当前支持 Windows，建议使用 64 位 Python 3.11。首次合成语音需要联网；OCR 在本机运行。没有翻译 API 密钥也可以朗读和截图识别。
| 功能 | 默认按键 | 操作 |
|---|---|---|
| 拖选朗读 | F14 | 按住模拟双击并保持鼠标左键，可拖动扩展选择；松开后读取选中文字 |
| 选中朗读 | F15 | 先自行选中文字，再按键朗读，不模拟鼠标选中 |
| 截图朗读 | F16 | 按键进入屏幕框选，拖动鼠标左键圈选文字，识别后朗读 |
- 单个英文单词优先查询本地 ECDICT；命中时不请求翻译 API。其他不含中文且未被判为代码的文本请求中文翻译。
- 中文内容直接朗读；疑似代码只朗读，不翻译。代码判断采用启发式规则，可能误判。
- 翻译前会将下划线替换为空格，并拆分驼峰命名，例如
WindowsSelectorEventLoopPolicy。 - 新操作会停止当前播放并取消上一轮异步处理；已经发出的后台网络请求可能仍会完成。
- 语音和译文缓存到本地，重复内容优先复用，减少等待和重复请求。
- 翻译结果显示在置顶浮窗中，可拖动、记住位置，双击关闭，约 99 秒后自动关闭。
- 查询单个英文单词时，显示本地词典中的音标、分词性中文释义、词形变化和学习标签。
- 翻译历史记录保存原文、译文、时间及出现次数，方便自行回顾。
在 GitHub 点击 Code → Download ZIP，解压到有写入权限的目录；也可以：
git clone https://github.com/xymsyh/xiaoxiao-reader.git
cd xiaoxiao-reader安装 Python 时启用加入 PATH 的选项。推荐 Python 3.11、64 位解释器。项目使用 Python 自带的 Tkinter，需要保留安装器的 Tcl/Tk 组件。
在项目目录打开 PowerShell：
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt这些命令不需要激活虚拟环境，也不需要修改 PowerShell 执行策略。没有 py 命令时，可使用对应 Python 3.11 的 python 命令创建虚拟环境。
.\.venv\Scripts\python.exe "01 ⭐️ 主程序.py"首次运行会在主程序旁自动生成 配置.ini，已有文件不会被覆盖。程序需要保持运行，控制台会显示实际按键；在控制台按 Ctrl+C 退出。
普通键盘没有 F14/F15/F16 很正常。 首次试用可先退出程序，将配置改为下面的 F8/F9/F10 方案，再重新启动。
在记事本输入并选中一段中文，按“选中朗读”键。确认可以播放后，再测试网页文字和截图 OCR。在线翻译需自行配置微软翻译密钥，详见后文。
朗读时最频繁的动作是“指向文字 → 选择 → 触发”。把触发键放在拇指附近，可以减少在鼠标和键盘之间切换，尤其适合高频阅读、查词和截图识别。G502 HERO 提供可编程按键，官方支持通过 G HUB 分配命令；其他能输出键盘按键的可编程鼠标也适用。G502 官方介绍
| 鼠标位置建议 | 映射键 | 功能 | 推荐场景 |
|---|---|---|---|
| 最容易按住并移动鼠标的拇指键 | F14 | 拖选朗读 | 单词、短语、网页段落 |
| 另一个顺手侧键 | F15 | 选中朗读 | 已选好的长段文本、编辑器中的内容 |
| 第三个空闲键，如不常用的 DPI 功能键 | F16 | 截图朗读 | 图片、扫描 PDF、视频字幕、不可复制文字 |
具体使用哪个物理键由握姿决定，保留左键、右键及滚轮的常规操作。上述是使用建议，不是项目预设的 G HUB 配置文件；项目不自动修改鼠标驱动设置。
- 打开鼠标厂商软件，例如 Logitech G HUB，选择鼠标和日常使用的配置文件。
- 在按键分配中，将三个空闲鼠标键分别映射为 F14、F15、F16。
- 保持
配置.ini中三个功能键与鼠标输出一致。 - 检查切换到浏览器、阅读器等应用时，鼠标软件是否自动切换了配置文件；让对应配置保持相同映射。
- 在记事本中验证：拖选键按住时能够继续拖动选择，松开时才触发朗读。
拖选键需要真实的按下/松开行为：按住鼠标键时保持键盘键按下，松开鼠标键时释放。 不要用“一次点击就发送完整按下和松开”的宏替代，否则无法持续拖选；也不要设置循环或连发。选择普通键盘按键映射，或使用驱动支持的等效按住行为。
不同驱动版本可选键列表不同。如果无法直接配置 F14/F15/F16，使用下面的 F8/F9/F10 方案即可，不必修改驱动内部文件。G HUB 的基础操作参考：官方按键分配说明。
读单词或短语： 鼠标指向文字，按住拖选侧键，按需拖动扩大选区，松开。程序朗读原文，适用时显示中文译文。不同应用的双击选择规则不同。
读一整段： 用鼠标或键盘先准确选好内容，再按选中朗读侧键。这种方式最容易控制选区，也适合不兼容双击拖选的应用。
读图片上的字： 按截图侧键，用左键拖出矩形，松开完成识别；按 Esc 或右键取消。截图不写入磁盘，识别出的文字会复制到剪贴板，然后进入朗读和翻译流程。
推荐从下面这组配置开始：
[按键映射]
拖选朗读 = f8
选中朗读 = f9
截图朗读 = f10| 设备条件 | 推荐做法 |
|---|---|
| 普通鼠标，无可编程侧键 | 主要使用“手动选中 → F9”，图片文字用 F10；F8 可由左手按住、右手移动鼠标 |
| 只有一个可用侧键 | 优先映射“选中朗读”（F15，或降级配置中的 F9），其他功能用键盘 |
| 两个可用侧键 | 优先分配“选中朗读”和“截图朗读”；频繁拖选时可把其中一个换成“拖选朗读” |
| 鼠标驱动没有 F14/F15/F16 | 鼠标映射 F8/F9/F10，并同步修改配置 |
| 笔记本功能键默认控制亮度/音量 | 检查 Fn/Fn Lock 设置，让功能键实际输出 F8/F9/F10 |
F8/F9/F10 容易在普通键盘上找到，但不保证与所有软件都不冲突。例如 F10 可能激活菜单，开发工具也常占用功能键。当前程序不拦截按键传递，目标应用仍可能响应；如有冲突，换成自己不用的单个键。F14/F15/F16 通常较少占用，因此仍是可编程鼠标的首选。
配置只支持三个互不冲突的单个键，暂不支持 ctrl+f9 等组合键，也不直接接受鼠标按钮名称。修改后必须重启。
查询单个英文单词时，程序优先读取随项目分发的 ECDICT SQLite 数据库。命中后完全跳过微软翻译接口，并显示音标、分词性中文释义、词形变化和学习标签。各区域均可拖动，双击关闭。
configuration
ECDICT 音标
kәn.figju'reiʃәn
─────────────────
1. 名词 结构, 表面配置, 外形, 配置
2. 计 配置
词形 复数 configurations
cet6 · toefl · ielts · gre
- 自动识别大小写、单词外围常见标点、内部撇号和连字符；短语、句子以及拆分后的驼峰/下划线标识符保持普通翻译布局。
- 本地库包含 401,258 个不含空格的词条，通过 SQLite 索引查询；运行时不解析 CSV，也不需要联网。
configured、configurations等词形会优先回到信息更完整的原形词条，并标明词形关系。- 音标直接使用 ECDICT 的
phonetic字段，不做 IPA 猜测、口音转换或人工修订；ECDICT 未提供音标时会明确提示。 - 本地未收录时才回退到现有在线翻译；没有配置 API 时会显示相应提示，朗读仍可使用。
- 数据版本、校验值、构建方式和许可证见 data/README.md。
朗读使用 edge-tts，不使用此处的翻译密钥。翻译使用微软 Translator 的文本翻译 REST API，需自行创建服务资源并获取密钥。
编辑主程序旁的 配置.ini：
[微软翻译API]
密钥 = 在这里填写你自己的密钥
区域 = eastasia
地址 = https://api.cognitive.microsofttranslator.com/translate- 密钥：填写自己的 Translator 资源密钥，不要加引号。留空时仍可朗读，已有翻译缓存仍可用；需要在线翻译时会显示配置提示。
- 区域：填写资源对应区域；示例
eastasia不代表你的资源一定在该区域。 - 地址：应为与当前微软翻译协议兼容的完整接口地址，包含
/translate。不能直接替换为 OpenAI 或其他厂商的聊天 API。 - 目标语言目前为简体中文
zh-Hans，原文语言交给翻译服务识别。
需要将实际朗读的声音同时发送到另一台设备或音频服务时，可在 配置.ini 中开启：
[音频发送]
启用 = true
地址 = https://audio.vui.ink/api/play程序会在后台发送与本地播放相同的 MP3，请求头为 Content-Type: audio/mpeg；接口需要的 X-Filename 由程序内部固定提供，无需配置。缓存命中的朗读也会发送；预渲染只生成缓存，不会发送。发送失败只会写入控制台，不会中断本地播放。关闭时将“启用”改为 false，修改配置后需要重启程序。
API 的申请、认证和服务额度以 微软官方快速入门 与 接口文档 为准。翻译服务可能产生费用，请自行查看所用资源的计费与额度。
本机 配置.ini 已被 Git 忽略，仓库只提供不含密钥的 配置示例.ini。不要在截图、Issue、提交或公开压缩包中附带真实密钥。
| 数据或操作 | 处理位置 / 行为 |
|---|---|
| 选中文字 | 通过模拟 Ctrl+C 读取；会改变剪贴板，成功时保留选中文字，不恢复原内容 |
| OCR 截图 | 截图保存在内存，使用 RapidOCR 在本机识别，不将图片上传给 OCR 服务 |
| 朗读文本 | 未命中语音缓存时，发送给 edge-tts 使用的在线语音服务 |
| 朗读音频 | [音频发送] 启用时，将最终播放的 MP3 发送到配置的网址 |
| 单个英文单词 | 优先查询本地 ECDICT；命中时不发送给翻译接口，本地未收录时才可能在线回退 |
| 其他待翻译文本 | 符合翻译条件且未命中缓存时，发送给配置的微软翻译接口 |
| OCR 识别文字 | 复制到剪贴板后进入相同的朗读/翻译流程，因此文本仍可能发送到在线服务 |
| 控制台 | 会显示朗读文本、识别结果和译文 |
| 本地词典 | 查询项目内的 data/dictionary.sqlite3，不发送额外网络请求 |
项目目录会生成以下本地文件，均不会随正常 Git 提交上传：
语音缓存/：MP3 音频及索引，索引包含文字和统计信息。翻译缓存.json：处理后的文本及译文。翻译记录.json：原文、译文、时间、次数等学习记录。翻译窗口位置.json：浮窗位置。配置.ini：本机按键和 API 凭据。
需要清理时，先退出程序，再删除对应缓存或记录；下一次使用会重新生成。缓存没有自动容量上限，也不是加密存储。打包分享请只打包仓库源码，不要直接压缩含个人缓存和配置的工作目录。
当前网络逻辑会清除本进程中的常见代理环境变量，并让翻译请求直连；不会修改系统代理设置。必须通过代理访问网络的环境需要调整代码，当前没有代理配置界面。
检查程序是否仍在运行、控制台显示的映射是否正确、鼠标驱动是否切换了应用配置、笔记本是否需要 Fn。先在普通记事本中测试。目标应用权限比程序高时，模拟输入可能受限；只有确实需要操作管理员应用时，再考虑以相同权限运行。
程序依赖目标应用支持 Ctrl+C，复制等待时间约 0.3 秒。剪贴板被其他软件占用、应用复制较慢、选区为空或不可复制时可能失败。优先改用“先手动选中 → 选中朗读”；图片或扫描内容用截图朗读。
检查系统音量、默认输出设备和控制台报错。首次合成需要联网，在线语音服务不可用时会失败。音频收集完成后才开始播放，不是收到第一块数据就播放，所以长段文字会有等待时间。
包含中文、被判断为代码、词典未收录、密钥未填写、网络失败或服务额度不足都可能导致不显示释义。单词命中本地词典时不需要翻译密钥。程序朗读的是原文，中文释义不会自动朗读。HTTP 401/403 请检查密钥和区域，429 请检查限流或额度。
第一次需初始化本地模型。尽量圈选清晰、字号较大、方向正常的文字，减少背景干扰；OCR 不保证准确还原复杂排版、公式或手写文字。项目包含多屏框选逻辑，具体 DPI 和屏幕组合仍需在自己的设备上验证。
确认安装依赖和启动程序使用的是同一个 .venv\Scripts\python.exe。OCR 需要 Pillow 和 rapidocr-onnxruntime。Tcl/Tk 缺失时，请修复 Python 安装并启用对应组件。
当前不支持。程序依赖 Windows 的 DPI、屏幕坐标和事件循环逻辑；不能仅修改快捷键后直接跨平台运行。
xiaoxiao-reader/
├── 01 ⭐️ 主程序.py # 朗读、翻译、OCR、窗口和按键处理
├── 配置读取.py # 首次配置生成与配置校验
├── 本地词典.py # 单词识别、SQLite 查询和结构化词条
├── 翻译卡片.py # 分层显示单词词条与在线译文
├── data/ # ECDICT SQLite、本地数据说明及许可证
├── tools/构建本地词典.py # 从固定 ECDICT 版本重建 SQLite
├── 配置示例.ini # 可公开的无密钥模板
├── 配置说明.md # 简短迁移说明
├── requirements.txt # 运行依赖
├── tests/ # 不调用在线服务的自动化检查
├── README.md
└── LICENSE
运行自动化检查：
.\.venv\Scripts\python.exe -m unittest discover -s tests -v测试覆盖配置生成/读取、错误配置、核心文本判断、本地词典、词形回查，以及本地/在线查询分流，不替代真实鼠标、声音设备、多屏环境及在线服务的人工验证。
欢迎通过 Issues 提交复现步骤，说明 Windows/Python 版本、功能键配置和报错；请去掉密钥与个人文本。后续可改进方向包括代理配置、缓存容量管理、剪贴板读取稳定性、组合键支持，以及更完整的跨设备测试。
感谢 ECDICT、edge-tts、RapidOCR、keyboard、mouse、Pygame、Pillow、Requests 和 Pyperclip 等开源项目。
本项目源码使用 MIT License。第三方依赖、在线语音和翻译服务分别遵循各自的许可证与服务条款。本项目与微软、罗技没有官方隶属关系。