MouseTooltipTranslator 使用指南：悬浮翻译、快捷键组合、OCR 与朗读功能全解

MouseTooltipTranslator 是一款以"鼠标悬浮即翻译"为核心的浏览器扩展，其官方使用指南（doc/pages/intro/intro_ro.md 为其中罗马尼亚语版本，与英文版 doc/pages/intro/intro.md 内容一致）系统性地介绍了它的十大功能：悬浮/选中翻译、TTS 发音、输入框写作翻译、URL 搜索词翻译、在线 PDF 翻译、YouTube/Netflix 双语字幕、图片 OCR、F2 自动朗读、语音识别翻译，以及目标语言切换与各项例外限制。本文完整继承该指南的操作步骤，并结合仓库源码（默认键位配置 src/util/setting_default.js、内容脚本 src/contentScript.js、OCR 视图 src/ocr/ocrView.js 等）逐项说明其底层触发机制与可验证依据，帮助你在安装后快速掌握全部用法并理解每个快捷键背后的实现。

功能总览与默认快捷键

指南中出现的所有快捷键都对应一组可配置的设置项，集中定义在 src/util/setting_default.js 的 keyboard 设置分组中。默认键位如下：

功能	默认按键	设置项	源码位置
显示翻译提示（默认始终开启）	always	showTooltipWhen	src/util/setting_default.js#L357-L362
提示出现时朗读（TTS）	左 Ctrl	TTSWhen	src/util/setting_default.js#L363-L368
翻译输入框中正在书写的文字	右 Alt	keyDownTranslateWriting	src/util/setting_default.js#L369-L374
自动阅读器（Auto Reader）	F2	keyDownAutoReader	src/util/setting_default.js#L386-L391
图片 OCR 触发键	左 Shift	keyDownOCR	src/util/setting_default.js#L398-L403
语音识别翻译	右 Ctrl	keySpeechRecognition	src/util/setting_default.js#L404-L409
悬浮取词粒度切换（词/句）	F8	keyHoldMouseoverTextType	src/util/setting_default.js#L410-L415

所有触发按键均可在设置页更换为指南中 keyList 列出的任意修饰键（左右 Ctrl/Alt/Shift/Meta）、鼠标点击（左/中/右键）、F2/F8/F9 或 null。此外，指南提到的"自定义快捷键"还可以通过浏览器内置的扩展快捷键页完成：从 chrome://extensions/shortcuts 进入，或将 chrome:// 替换为对应浏览器的内部地址前缀（如 edge://、brave://、browser://）。

基础用法：悬浮或选中文字即翻译

指南第一条即最核心的用法：将鼠标悬停在文字上，或选中（高亮）文字，即可弹出翻译提示（ToolTip）。指南给出了一段示例文本用于测试悬浮效果：

Proletarier aller Länder, vereinigt euch!

如果翻译没有出现，指南要求检查当前目标语言设置；并特别指出：当源语言与目标语言相同时，该翻译器会省略（跳过）这段文字。

从源码可以印证这条规则：在 src/contentScript.js#L269-L282 中，每次取词完成翻译请求后，若返回的 sourceLang == targetLang（或源语言在排除列表中），会直接调用 hideTooltip() 隐藏提示，因此同语言文本不会重复显示译文。悬浮检测本身由内容脚本对 mousemove 事件做防抖（debounce）处理：src/event/mouseover.js#L34-L37 中每次鼠标移动都会按 mouseoverEventInterval（默认 300 毫秒）延迟后重新取词，scroll 事件也会触发同样的延迟检测，保证翻页滚动时提示跟随更新。

TTS 发音：按住左 Ctrl 听原文，双击听译文

指南的第二项功能：

• 按住 left-Ctrl 键，当翻译提示出现时会用 TTS 朗读原文发音；按 Esc 可停止发音；
• 快速双击 left-Ctrl 可以改为朗读翻译后的结果文本（即译文发音）。

源码层面的对应关系很清晰：

• TTSWhen 默认值正是 ControlLeft（src/util/setting_default.js#L363-L368），提示展示时由 src/contentScript.js#L220-L222 判断 TTS 是否应随提示启动；
• "双击听译文"由双击检测实现：src/contentScript.js#L882-L894 的 recordDoublePress() 记录每次按键时间戳，若两次按下间隔小于 1000 毫秒则置位 keyDownDoublePress，随后 isTtsSwap = keyDownDoublePress[setting["TTSWhen"]]（L222）决定朗读目标切换为译文（target）而非原文（source）。

输入框写作翻译：右 Alt 一键翻译正在输入的内容

指南的第三项功能：

• 在输入框中按下 right-Alt 键，可翻译你正在书写的文字（或当前选中的文字）；如需撤销，按 Ctrl + Z 即可还原；
• 若翻译不生效，请确认当前目标语言与你的书写语言匹配；
• 如果 right-Alt 在你的键盘布局中被用作 Hangul（韩文）切换或 AltGr 组合键，请改绑其他按键使用。

实现见 src/contentScript.js#L563-L569 的 translateWriting()：它先通过 dom_util.getFocusedWritingBox() 确认焦点确实在"书写框"中（Google Docs 场景下跳过此判断，由专门的 Google Docs 注入脚本接管）。源码注释还解释了双击防竞态：整个流程（IME 收尾 → 请求翻译 → 插回选区）是异步的，若运行中再次按键会与选区/插入产生竞争，因此对重入按键做了忽略处理。

针对指南中"右 Alt 被 Hangul Swap 占用"的提示，仓库还提供了一个相关开关 ignoreAltGr（src/util/setting_default.js#L375-L385）：开启后，国际键盘布局上以 Ctrl+AltRight 形式到达的 AltGr 按键会被当作普通打字处理，不再误触 AltRight 绑定的翻译动作。

URL 搜索框翻译：/ + 空格

指南第四项：在 URL/搜索框中输入 / + Space（即在查询词之前键入斜杠加空格），可翻译该搜索框中的文本。

在线 PDF 支持（基于 PDF.js）

指南第五项：支持在线阅读的 PDF 文件显示翻译提示，PDF 渲染采用 PDF.js（PDF.js Viewer）。本地计算机上的 PDF 文件则需要额外权限，详见下文"例外"一节。

仓库内 PDF 支持的基础设施可以确认：

• public/pdfjs/web/viewer.html 及配套的 cmaps、locale、standard_fonts 等资源随扩展分发；
• public/manifest.json 中 "web_accessible_resources" 声明了 pdfjs/web/viewer.html 等资源对所有站点可访问；
• src/pdf/pdfInject.js 负责向 PDF.js 阅读器注入内容脚本，并会读取 uiLanguage 设置，在 webviewerloaded 事件后将 PDF.js 工具栏本地化为所选 UI 语言（src/pdf/pdfInject.js#L29-L49）。

YouTube 与 Netflix 双语字幕

指南第六项：支持 YouTube 和 Netflix 的双语（dual）字幕——即在播放页同时呈现原文与译文两行字幕。

从源码结构看，字幕检测类型由设置项 detectSubtitle 控制，默认值即 "dualsub"（双语字幕），可选值还包括 targetsinglesub（仅译文）、sourcesinglesub（仅原文）与 null（关闭），见 src/util/setting_default.js#L145-L150 与 #L349-L354；具体的站点适配逻辑位于 src/subtitle/ 目录（youtube.js、netflix.js、svt.js 等按站点拆分）。

图片 OCR：按住左 Shift 悬停图片

指南第七项：按住 left-Shift 键并将鼠标悬停在图片（例如漫画）上，即可触发 OCR 识别并翻译图中文字。

该功能的入口与门槛判断可直接在源码中验证：

• src/ocr/ocrView.js#L28-L34 的 checkImage() 首先检查 keyDownList[currentSetting["keyDownOCR"]]——即当前是否正按住 OCR 触发键（默认 ShiftLeft），未按住则直接返回；随后通过 util.getPointedImg(x, y) 确认鼠标确实指向一张尚未处理过的图片（ocrHistory[img.src] 去重）；
• 识别引擎为 tesseract.js（detect 调用，见 src/event/mouseover.js#L7），OCR 在扩展的 ocr.html iframe 中执行，同时并行运行多种边界框策略（纯 tesseract、opencv 小框、整框、白底/黑底预处理等，见 src/ocr/ocrView.js#L59-L80），OpenCV 相关计算运行在 public/opencvHandler.html 这个 manifest 声明的 sandbox 页中。

自动阅读器：按 F2 逐句朗读

指南第八项：

• 按下 F2 键启动自动阅读器：从鼠标所指文字开始，用 TTS 连续朗读到文末；
• 按 Esc 停止自动朗读；
• 快速双击 F2 可以改为朗读翻译后的结果文本。

源码对应 src/contentScript.js#L956-L972 的 startAutoReader()：它先校验当前确实按住了 keyDownAutoReader 绑定的键（默认 F2），再读取 keyDownDoublePress 判断是否为双击（决定朗读原文还是译文），然后从鼠标当前位置已检测到的 mouseoverRange 开始执行 processAutoReader()。阅读过程中还支持方向键控制：左右键切换上/下段、上下键调节语速（src/contentScript.js#L984-L989）。按任意字符键会自动停止朗读（src/contentScript.js#L941-L944），与指南"按 Esc 停止"的体验一致。

语音识别翻译：按住右 Ctrl 说话

指南第九项：

• 按住 right-ctrl 键激活语音识别翻译；
• 语音识别的默认语言是英语；
• 若识别语言与目标语言相同，则跳过翻译；
• 需要麦克风（音频）权限；
• 仅兼容基于 Chromium 的浏览器，如 Google Chrome、MS-Edge、Vivaldi、Opera、Brave、Arc、Yandex。

实现见 src/speech/index.js：initSpeechRecognition() 通过 window.SpeechRecognition || window.webkitSpeechRecognition 获取引擎，引擎不存在时直接不可用——这正是"仅 Chromium 系"限制的来源（Firefox 未实现该 Web Speech API）。识别语言由设置项 speechRecognitionLanguage 控制，默认值为 en-US（src/util/setting_default.js#L739-L743），按下 keySpeechRecognition（默认 ControlRight）时由 src/contentScript.js#L910-L912 调用 speech.startSpeechRecognition() 启动。

更改目标语言

指南"Change Language"一节的操作步骤：

1. 在设置页中更改当前（目标）语言；
2. 设置页的入口：点击浏览器右上角的拼图（扩展）按钮打开扩展菜单进入设置页。

从源码结构看，目标语言对应设置项 translateTarget，默认值为 "en"（src/util/setting_default.js#L253-L256），候选语言列表来自 src/util/lang.js 的 langList，并额外提供 Auto（自动检测源语言）与 None 等选项（见 src/util/setting_default.js#L9-L11 的语言表合并逻辑）。因此排查"翻译不出来"时，第一个要核对的就是 translateTarget 是否设置为你期望的目标语言。

例外与限制（Exception）

指南最后列出的所有例外情形，逐条整理如下（均可在仓库中找到对应依据）：

• 源语言与目标语言相同时跳过：对应 src/contentScript.js#L275-L282 中 sourceLang == targetLang 即 hideTooltip() 的逻辑；

• 页面未聚焦时检测不到按键输入：键盘事件监听挂在页面 window 上（如 src/event/mouseover.js#L34 的 window.addEventListener），浏览器只对聚焦的标签页派发按键事件，所以使用前需先点击页面使其聚焦；

• 网页处于离线状态时扩展不工作：翻译请求依赖在线翻译服务（src/translator/ 目录下各服务商实现），离线无法请求；

• 在 Chrome 扩展商店页面（chrome.google.com/extensions）上不工作：这是 Chrome 的安全策略限制，商店页面对内容脚本注入有专门保护；

• 本地 PDF 需要文件访问权限：

  1. 若文件打不开，可尝试将 PDF 拖拽到标签页上打开；
  2. 页面会显示权限警告并跳转到权限设置页；
  3. 在跳转后的页面中勾选 "允许访问文件 URL"（Allow access to file URLs）；
  4. 重新打开该 PDF 使权限立即生效。

小结

对照官方使用指南，MouseTooltipTranslator 的核心操作可归纳为一张速查表：

操作	按键/输入	说明
悬浮/选中翻译	鼠标悬停、划选	默认 always，始终可用
听原文发音	按住 Ctrl（左）	提示出现时朗读原文，Esc 停止
听译文发音	双击 Ctrl（左）	1 秒内双击切换朗读目标
翻译输入框文字	Alt（右）	Ctrl+Z 可撤销；Hangul 布局需改键
翻译搜索框文字	/ + Space	在查询词之前键入
图片 OCR	按住 Shift（左）+ 悬停图片	基于 tesseract.js + OpenCV 预处理
自动朗读	F2	双击听译文；Esc/字符键停止；方向键控制
语音识别翻译	按住 Ctrl（右）	默认识别英语；仅 Chromium 系浏览器
词/句粒度切换	按住 F8	悬浮取词在 word/sentence 间切换

以上按键均可在设置页的 keyboard 分组中重新绑定，扩展快捷键则通过浏览器 chrome://extensions/shortcuts 一类页面配置。所有默认值与触发逻辑均可在 src/util/setting_default.js、src/contentScript.js、src/ocr/ocrView.js 与 src/speech/index.js 中逐条对照验证，方便你在二次开发或排障时快速定位行为来源。