FluentRead 网页翻译与划词翻译完整指南：双语模式、全文翻译、悬浮球与句子高亮

• 前端
• AI 应用
• 本地部署

FluentRead 是一款开源的双语翻译浏览器插件，其核心能力围绕"网页翻译 + 划词翻译 + 悬停翻译"展开，所有译文都直接呈现在当前网页上。本文将系统讲解这三大翻译形态的完整使用流程，深入剖析全文翻译的弹窗优先级处理、页面悬浮球的高级外观参数、双语句子高亮的对齐原理，以及段落处理、请求限流与多语言目录等进阶配置，并结合仓库源码说明各项设置的底层实现，帮助你把这套翻译能力真正调到顺手。

网页翻译：双语并列与按需恢复

打开 FluentRead 并点击网页翻译按钮，页面会进入双语模式：每段译文紧贴其原文段落显示，标题、链接与文章结构保持原样，便于随时对照阅读；在支持的前提下，常见的行内公式也会被保留。翻译默认跟随你的阅读位置推进——滚动到哪一段，就翻译哪一段。如果你希望一次处理整页内容，可以在设置中选择整页处理（whole-page processing）；之后随时可以恢复原文，再换一种语言或另一个翻译服务重新翻译。

原文与译文并列展示的效果可以参考下图（中文段落在上、英文译文紧随其下的双语版式，同时保留站点标题、导航链接等页面结构）：

弹窗与模态框出现时怎么办

当公告条（announcement）或模态弹窗（modal dialog）挡住了页面时，全文翻译会先处理当前的活动弹窗，等你关闭弹窗后自动继续翻译页面其余部分。如果翻译过程中出现弹窗，未完成的页面任务会被暂停，但已有译文保持不变；开启进度反馈时，界面会说明"弹窗关闭后将恢复翻译"。恢复原文会同时取消这个自动续翻流程。非阻塞的通知条与面板不会暂停页面翻译。

这一行为在源码中有明确实现。modalPriority.ts（src/features/full-page-translation/content/modalPriority.ts）负责识别"当前真正阻塞页面交互的弹窗"，它的判定依据包括：

• 原生dialog:modal元素；
• 显式声明aria-modal="true"的对话框角色元素；
• 带有遮罩层或滚动锁（页面overflow被设为hidden）证据的常见组件弹窗（.modal、.ant-modal、.el-dialog等）；
• 通过可见性、遮挡证据与堆叠顺序（z-index）选出最顶层的弹窗，并支持穿透开放的 Shadow DOM 判断归属。

也就是说，全页翻译不会盲目地把页面内所有对话框都当障碍处理，而是只针对真正阻断交互的顶层弹窗做"先弹窗、后页面"的调度。

页面悬浮球：一个常驻的翻译快捷入口

在设置 → 常规 → 页面助手（Page helpers）中开启全页翻译悬浮球（Full-page translation ball），页面边缘会出现一个常驻悬浮球：单击翻译整个网页，再次单击恢复原文，按住可以上下拖动，松手时会自动停靠到较近的一侧（左或右）。

悬浮球高级设置（Floating ball advanced settings）可以精细调整其余行为。这些参数在 src/features/floating-ball/types.ts 中被定义为一个统一的展示契约FloatingBallPresentation，组件侧（src/features/floating-ball/ui/FloatingBall.vue）通过合并默认值来消费，具体包括：

• 按钮显示（Button display）：翻译与设置按钮支持"悬停展开"（hover）、"始终显示"（always）或完全隐藏、只留球体（hidden）三种模式。
• 展开延迟（Expand delay）：指针停留多久后按钮才展开，默认立即展开（0 毫秒）；调大延迟可以避免指针掠过页面边缘时的误展开。注意键盘聚焦总是立即展开，不受延迟影响。
• 点击行为（Click action）：点击球体本身可以切换翻译、打开设置页，或什么都不做（仅作为拖动手柄）。按住拖动则始终生效。
• 更小悬浮球（Smaller ball）：使用缩小尺寸（组件中普通尺寸为 48px、紧凑尺寸为 36px），减少对页面的遮挡。
• 设置入口（Settings entry）：可以隐藏悬浮球上打开设置页的按钮。
• 收起透明度（Collapsed opacity）：收起状态下的不透明度（百分比，默认 52），数值越低越透明；悬停、展开和拖动时始终以完全不透明显示。

从组件实现看，拖动通过指针位移阈值（DRAG_THRESHOLD = 6像素）区分"点击"与"拖动"，拖动结束后根据指针落在视口左半还是右半决定停靠侧；按下Escape可以收起已展开的悬浮球。关闭悬浮球后，全页翻译快捷键（默认Alt+T）与右键菜单入口不受影响。

按钮等界面控件只显示译文

按钮、标签页、表单标签与工具栏操作项属于"界面控件"，其尺寸被站点自身样式固定。在双语模式下，这类文本采用替换策略（replaced by the translation）而非"原文+译文堆叠"：按钮不会被撑高、标签不会溢出、工具栏行不会被拆散。原生按钮、带role控件语义的元素、按钮样式链接以及由input元素构建的按钮都遵循同一规则；恢复原文时，原始标签会原样放回。

而段落、标题与折叠区中的完整句子仍遵循你选择的显示模式，因此双语阅读体验不受影响。此外，随表单提交的按钮（带name属性的 submit 按钮）和文本框内容会被保留不动，站点不会收到它无法识别的动作，你自己的输入也不会被改写。

菜单或界面文字缺失怎么办

在高级设置 → 页面识别（Page recognition）中开启"识别所有节点"选项，恢复页面后重新翻译，即可覆盖翻译进行期间新出现的可见菜单与导航。但更广的识别范围也会改变更多界面文字，如果不需要，关闭该选项并在下一次翻译时回到常规范围。至于图片或图表内绘制的文字，请改用图片翻译或区域翻译。

段落处理方式的进阶调节

高级设置（Advanced settings）提供若干针对网页翻译的细粒度控制，每一项都在下一次翻译时生效：

• 侧边栏翻译（Sidebar translation）：在阅读正文的同时也翻译侧边栏与导航，页头页脚保持不变。
• 段落最少字符数（Minimum characters per paragraph）：跳过短于该长度的段落，减少为碎片文本发出的请求。长度按字符数计算，例如hello计为 5 个字符。
• 免滚动翻译字符数（Characters translated without scrolling）：进入页面后立即翻译页面顶部这么多字符，其余部分跟随阅读进度；设为 0 则完全依赖视口触发。
• 长段落断行（Line breaks in long paragraphs）：在较长译文的每个句子结尾插入换行。
• 译文在上（Translation before original）：双语模式下把译文放在每段原文上方而不是下方。

这些阈值在配置层有明确的默认值与取值范围。src/core/config/pageTranslation.ts 定义了DEFAULT_MIN_TRANSLATION_TEXT_LENGTH = 2（可选范围 1–100，默认过滤单字符碎片）和DEFAULT_EAGER_TRANSLATION_CHARACTERS = 0（可选范围 0–100000），并提供normalizeMinTranslationTextLength、normalizeEagerTranslationCharacters两个纯函数把任意存储值收敛回合法区间。而"免滚动字符预算"在内容脚本中由 src/features/full-page-translation/content/eagerTranslation.ts 消费：会话首次遇到候选段落时冻结预算，按发现顺序扣减字符量，预算耗尽后交还给视口驱动的常规调度——这也解释了为什么修改设置要等下一次翻译才生效。

双语句子高亮：原文与译文的逐句联动

在设置 → 常规 → 双语句子高亮（Bilingual sentence highlighting）中开启该功能后，把鼠标悬停在一侧句子上，另一侧对应的句子会被同时高亮，无需点击或快捷键。设置页的预览区内置了若干组句子对供你试用。

其实现依赖原生 CSS Custom Highlight API 与按句对齐算法：

• src/features/full-page-translation/content/sentenceHighlight.ts 只读收集宿主文本与译文容器文本，逐帧合并指针事件（requestAnimationFrame），用原生Highlight绘制高亮；离开文本、开始选择、滚动、节点变化或页面隐藏时释放范围与监听器，不拆分宿主文本、不更改排版、不发起任何翻译请求。
• 句子对齐算法位于 src/core/translation/sentenceAlignment.ts：优先使用Intl.Segmenter做原生分句（含对Mr.、Dr.等缩写与空白的保护，另提供兼容回退），句子数相等时按顺序一一配对；句子被拆分或合并时，则基于"顺序 + 相对累计长度"约束性地分组。

需要说明的是，这种对齐是局部近似，不能验证翻译准确性，对大幅改写或重排语序的文本可能不完全匹配。高亮本身不发送翻译请求，也不改变页面文本与布局。该功能仅在双语模式下生效；恢复原文、关闭该选项、离开文本或选中文字都会清除高亮。不支持 CSS Custom Highlight API 的浏览器会退回普通翻译、只是没有高亮。

划词翻译：选中即译、随取随用

在扩展菜单中开启双语划词翻译，然后在页面上选中一个词或一段话，点击附近出现的图标即可翻译。结果卡片支持：

• 复制译文或朗读原文；
• 拖动卡片头部或内容周围的空白区域移动窗口，拖动任意边缘或角落调整大小；
• 文本自动换行以适配宽度，长内容在卡片内部滚动；
• 你对位置和大小的调整在卡片关闭前一直保持；重新选择文本时，会在选中文本附近以默认尺寸重新打开。

划词翻译的触发方式可以更换为直接弹窗、某个按键或其他手势，也可以调整触发延迟。对于快速翻译来说，一个常规翻译服务就足够了。

悬停翻译：段落级随指随译

将鼠标悬停在一个段落上并按Control键即可翻译该段，无需选中文本，也不必翻译整页。相关快捷键的修改方式见快捷键与触发方式。

同一段落也可以直接取为文本：指向段落并按Alt+C（Mac 上为 Option+C）即可把鼠标下方的段落复制到剪贴板。已翻译的段落按当前显示方式复制。开关、快捷键以及复制内容（匹配显示 / 原文 / 译文 / 原文+译文）都可以在设置 → 翻译 → 段落复制（Paragraph copy）中调整。

AI 阅读卡片与学习中心

阅读卡片可以解释语气、拆解长句、展示用法或生成一道练习题，它使用已配置的 AI 服务，在你选择动作时才启动。而学习中心可以保存单词、短语和句子，方便日后在原文语境中复习。

图片、文件与字幕翻译

• 图片翻译：在原文图片上方显示可读的译文文本。
• 区域翻译：圈选屏幕上的小范围区域，得到可复制的文本。
• 文档翻译：导入、阅读、编辑并下载文件。
• 视频字幕：在 YouTube 和 X 上使用双语字幕。

服务与设置：免费服务、接入 Provider 与请求限流

你可以直接使用开箱即用的免费翻译服务，也可以接入自己的翻译服务，例如 DeepL、各类 AI 服务或本地 Ollama 模型。受支持的 AI 服务还可以使用术语表。

在高级选项 → 请求限制（Request limits）中，翻译并发数默认为10，同时默认每秒 10 次请求、每分钟 250 次。已保存的旧设置会被保留。把每秒或每分钟的限速设为0即可关闭对应限制。

请求限流并非一个简单的全局开关。src/core/config/requestLimits.ts 定义了全局、服务级、模型级三档限流配置契约，并实现了"模型级 custom 优先 → 服务级 custom → 全局共享 bucket"的解析顺序（resolveRequestLimits）；默认值集中在 src/core/config/scheduling.ts（并发 10、每秒 10、每分钟 250）。也就是说，你可以为某个特定服务甚至特定模型单独设置更严格或更宽松的额度，未单独配置时自动回退到全局默认。

更多翻译语言：52 种语言的选择与限制

源语言与目标语言选择器现在提供52 种语言选项，涵盖简体/繁体中文、德语、葡萄牙语、意大利语、阿拉伯语、印地语、越南语、泰语、乌克兰语与斯瓦希里语等。输入翻译与写作助手共用同一份语言列表。自动检测源语言仍然可用，已有语言设置会被保留。这份目录在 src/core/language/catalog.ts 中以稳定的语言码维护，简体中文（zh-Hans）与繁体中文（zh-Hant）被独立列出。

实际使用中有几点需要注意：

• 语言对覆盖因服务而异：机器翻译服务、AI 模型与 Chrome 内置翻译对语言的支持程度并不一致，列表中的语言不代表每个服务都支持。
• 图片 OCR 与视频语音识别仍依赖各自的 OCR 语言包或语音模型，与翻译语言列表相互独立。
• DeepL 目前不支持卡纳达语（Kannada）或僧伽罗语（Sinhala），选择这两种语言时会提示你改用其他服务。
• 语言码会自动转换：Google 与 NiuTrans 的挪威语代码、Microsoft 的塞尔维亚语代码都会被自动映射为对应服务认可的写法，无需手动处理。

小结

FluentRead 的翻译能力可以概括为一条主链路（网页/划词/悬停三种入口）加若干精细调节维度：全文翻译支持"跟随阅读位置 / 整页处理"两种模式与弹窗优先级调度，悬浮球提供七项外观与交互参数，双语句子高亮基于原生HighlightAPI 与顺序+长度对齐，段落最少字符数、免滚动字符预算、三层请求限流与 52 语言目录则构成进阶配置的完整拼图。配合设置中心、站点适配与自定义站点规则，你可以针对不同站点和不同阅读场景组合出最适合自己的双语阅读方案。

• 前端
• AI 应用
• 本地部署