手写Logseq PDF翻译插件：从选区捕获到译文回填的完整实践

读文献看到一半想立刻看中文手却本能地切去浏览器、打开翻译页、复制粘贴、再切回笔记软件来回折腾七八次思路断得干干净净。这就是我最初在 Logseq 里啃 PDF 论文时的真实状态。市面上确实有现成的翻译插件但要么只支持某些固定平台要么翻译质量完全不可控。后来我不想再将就了索性用 Logseq 插件 API 自己写了一个 PDF Translator。这篇文章会完整记录我从需求拆解、API 摸底、核心实现到发布迭代的全过程不只讲代码怎么写还会重点聊聊实测里踩过的坐标漂移、请求竞态、UI 清理这几个坑。如果你正打算开发 Logseq 插件或者想把 PDF 翻译能力内联进自己的工作流这篇文章应该能让你少走不少弯路。1. 从场景痛点梳理插件目标我不是在做“翻译工具”而是在做“阅读流水线”1.1 最初触发需求的真实场景我平时读论文的方式和很多人一样把 PDF 直接拖进 Logseq 的白板或页面里然后在右侧边栏打开文件阅读器。Logseq 的双链和引用能力对文献笔记很友好但缺一个关键环节——翻译。那个痛点是“割裂感”。我在 PDF 里读到一段关键论证需要立刻看中文辅助理解。典型的动作是复制文本、切换到浏览器翻译页、粘贴、看译文、再切回来。一次两次还能忍一篇文章二三十处需要翻译时整个阅读节奏就被打碎了。而且 Logseq 本身的块引用能力需要我先退出 PDF 阅读器才能记笔记更别说在阅读过程中保持心流了。后来我试图在插件市场找现成方案。搜索结果里的 PDF 工具不少但翻译相关的几乎都是针对 Zotero 或 Obsidian 的Logseq 生态里没有真正能用的“划词翻译 译文回填”工具。那一刻我就意识到这个需求值得自己动手而且用 Logseq 插件机制实现是完全可行的。1.2 备选方案对比“外挂”与“内联”的取舍在决定自己写插件之前我把可能的方案都列了一遍逐个对比过方案优点缺点浏览器翻译扩展免费、即装即用、整页翻译无法直接翻译笔记库里的 PDF需要来回切换窗口与 Logseq 双链工作流完全脱节外部划词翻译工具在任意应用中通过快捷键划词翻译只能看译文无法沉淀到笔记翻译状态不会跟着 Logseq 页面持久化本地部署翻译服务如 LibreTranslate隐私可控、免费额度高部署成本高普通用户上手门槛大单机翻译质量有限自己写 Logseq 插件深度内联到阅读流程可收集、可缓存、可扩展开发调试成本由自己承担需要熟悉插件 API 和 PDF 渲染机制对比完我确定了一个结论核心价值不在于“调用翻译接口”这个动作而在于把翻译无缝嵌入 Logseq 的阅读链路里。用户选中 PDF 文本译文立刻被提取用户按快捷键译文被追加为笔记块。翻译不是终点理解文献和沉淀笔记才是。1.3 确定功能边界与交互形态想清楚目标后我给插件画了一条明确的边界线核心功能在 Logseq 内置 PDF 阅读器中划词翻译译文以浮动气泡展示。延伸功能将翻译结果按快捷键收集到当页笔记块中方便后续整理。不做全文翻译PDF 排版复杂整页直译必然破坏版式且消耗 API 额度。专注“按需翻译”更贴合研究场景。不做术语库第一版先支持通用翻译把架构做成可扩展后续再引入术语术语表。交互形态上我参考了常见划词翻译工具的做法选中文本后在选区附近弹出一个小气泡卡片显示译文和原文对照再按一个快捷键就把当前翻译记录写入笔记。这个设计既能保证阅读不中断又给“沉淀笔记”留了一条通路。2. 开发前先摸清 Logseq 插件运行机制与 API 家底2.1 插件运行模型iframe 里的受限 Web 应用刚开始做 Logseq 插件很多人会把它当成普通 Web 扩展去写这是第一个认知误区。Logseq 插件通常运行在独立的 iframe 里与主应用的内容区有比较严格的 DOM 隔离。主应用通过logseq全局对象向插件暴露 API插件通过注册「UI Item」「Slash Command」「命令面板入口」等方式把功能挂接回主界面。这个模型带来的直接后果是你不能像写浏览器油猴脚本那样直接操作 Logseq 底层 DOM。插件能访问到的 DOM 范围主要取决于logseq.App.registerUIItem挂载的区域。比如注册侧边栏按钮得到的是一个侧边栏容器的 iframe注册斜杠命令实际入口在主应用菜单层但回调逻辑依然跑在插件 iframe 里。因此拿到 PDF 阅读器选区的关键是去操作插件自己 iframe 内可以获取的 DOM Selection而不是幻想直接注入主应用 DOM。2.2 与笔记正文选区相关的 APIgetSelectedText 与 DOM SelectionLogseq 官方提供了logseq.Editor.getSelectedText()能拿到当前编辑区选中的纯文本。这个 API 对普通块注释很有效但对 PDF 阅读器场景基本不管用。原因在于 PDF 阅读器内部的文本选择和编辑器选区是两条独立链路。实测下来真正可靠的方法是用浏览器原生的window.getSelection()配合getRangeAt(0).getBoundingClientRect()拿到选区在视口中的坐标。因为 PDF 的文本层用的是 DOM 文本节点浏览器选中后Selection API 天然可以读到文本内容与几何信息。这个方法不依赖 Logseq 官方对 PDF 选区的特定支持兼容性反而更好。有一点要特别注意getSelectedText()返回的是笔记编辑区的文本而不是 PDF 里的文本。如果你在 PDF 里划词后去调用它大概率拿到一个空字符串或上一个笔记块的残影。我第一版就踩了这个坑后来彻底切到了 DOM Selection 方案。2.3 PDF 渲染层为什么不能直接“改写 PDF 文本”Logseq 内置 PDF 阅读器基于 pdf.js页面主体通过 canvas 绘制文本层则是一层透明的 DOM 节点覆盖在 canvas 上方。这里有个关键事实canvas 绘制出来的图像无法被程序直接改字。所以“直接在 PDF 上替换成英文译文字符串”这个听起来很自然的方案物理上走不通。可行的路径只有两条一是在选区上方叠加一个浮层气泡用 CSS 定位让译文“悬浮”在原文旁边二是把译文收集到笔记区异步或手动地写回日志页面。我的最终实现是两者兼有划词翻译后默认弹气泡按下收集快捷键则把当前译文写成一条带引用的笔记块。2.4 翻译服务接入的抽象层provider 模式翻译服务平台五花八门有 DeepL、OpenAI 兼容接口、各类通用翻译 API 等。我不希望代码里写死某一家于是设计了一个轻量 provider 抽象interface TranslatorProvider { name: string; translate(text: string, targetLang: string): Promisestring; }每个 provider 只需实现name和translate方法就可以被插件核心逻辑复用。用户可以在设置面板里选择当前使用哪个 provider也可以填自己的自定义 base_url 来对接自建服务。这个设计让插件在面对 API 失效、服务商改版时不需要动核心逻辑换一个 provider 即可。选型方面的建议如果追求翻译质量和长文本表现OpenAI 兼容接口的“理解式翻译”效果明显优于传统词典式机翻如果追求免费额度各类通用翻译 API 的每日免费额度也够个人阅读用。我在默认实现里同时放了 OpenAI 兼容接口和一个通用翻译接口并在文档中写清楚各自的鉴权信息配置方法。3. 核心实现链路选中、翻译、展示的完整走通3.1 捕获选区定位文本内容与页面坐标捕获选区是所有后续动作的起点。我封装了一个函数专门从当前 PDF 视口里读取选中信息function getPdfSelection(): { text: string; rect: { x: number; y: number; width: number; height: number } } | null { const sel window.getSelection(); if (!sel || sel.isCollapsed || sel.rangeCount 0) { return null; } const range sel.getRangeAt(0); const rect range.getBoundingClientRect(); return { text: sel.toString().trim(), rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, }; }这里有一个重要设计坐标信息必须在“捕获选区”的同一帧内取完。如果先拿文本、再取坐标用户可能已经滚动页面或者取消选区拿到的坐标就是无效坐标。我最初分两步取结果气泡经常出现在屏幕边缘或错误位置。后来改成一次性读取问题基本解决。拿到坐标后浮层气泡才能做到“贴近原文”。气泡的定位方式不是简单地position: fixed加top/left而是要考虑到 Logseq 阅读器自身可能带有的内部滚动容器。层级和定位容错是实际开发里绕不开的重头戏这部分我会在第四部分集中讲。3.2 翻译请求并发控制与错误兜底翻译请求本身不复杂复杂的是高频划词场景下的并发管理。用户读论文的时候节奏是很快的划词、看译文、再划词、再看译文。如果每次划词都直接发请求上一轮的响应可能比下一轮还晚到气泡内容就会闪烁错乱。我的方案是引入一个自增requestIdlet requestSeq 0; async function requestTranslate(text: string, targetLang: string) { const currentSeq requestSeq; const result await provider.translate(text, targetLang); if (currentSeq ! requestSeq) { return; // 这条响应已经过期直接丢弃 } renderBubble(result, lastSelectionRect); }当用户快速划过另一段文本时较早发出去的请求依然会把 result 返回但因为requestSeq变了它就不会再渲染到界面上。这个机制虽然简单但在实际测试中非常有效几乎消除了“译文闪烁跳动”的体验问题。错误兜底方面我处理了三种异常网络超时、API 鉴权失败、返回空值。前两种统一在气泡里显示“翻译失败请检查接口配置”的提示第三种则直接不显示气泡因为大概率是选中的文本不可翻译。考虑到 API 有速率限制我还在请求层加了一个简单的队列避免短时间内集中轰炸翻译服务。3.3 译文呈现气泡模式与侧边栏收集模式气泡模式是即时反馈逻辑简单完整实现了译文回填的核心体验。用户在 PDF 中选中一段文字气泡就出现在选区附近展示翻译结果并略作延迟1.5 秒后自动淡出。气泡内容由三部分组成译文正文多语言混排时正文按原文换行拆段原文引用行用于对照避免歧义底部操作区“复制译文”、“写入笔记”两个按钮写入笔记操作是我最喜欢的一个设计。点击“写入笔记”后插件会把选中原文、译文、当前页码和所属页面路径一起插到当前日志或指定页面里成为一条标准 Logseq 块。这样之后搜索笔记时译文块和原文 PDF 的引用关系都保留了上下文。3.4 最小可用实现骨架核心代码把整条链路串起来核心逻辑并不复杂import { logseq as Plugin } from logseq/libs; async function main() { Plugin.on(ui:visible:changed, ({ visible }) { if (visible) { // 侧边栏 UI 展示时做初始化 } }); // 划词翻译主入口 document.addEventListener(mouseup, async () { const selection getPdfSelection(); if (!selection || selection.text.length 2) return; const targetLang await getSetting(targetLang); await requestTranslate(selection.text, targetLang); }); // 注册命令面板入口 Plugin.App.registerCommandPalette({ key: pdf-translate-collect, label: 收集当前翻译到笔记, keybinding: { mode: global, binding: modshiftt }, }); } export default main;实际生产版本会在此基础上增加生命周期清理、设置面板响应和 provider 切换逻辑但主干就是这三步取选区、调翻译、渲染结果。太多的框架化设计反而会让插件失去轻量优势。4. 实测中最容易翻车的三个环节4.1 PDF 缩放与滚动导致的坐标漂移这是整个开发里最让我头疼的问题没有之一。Logseq PDF 阅读器支持缩放和上下滚动PDF 文本层的坐标是相对页面的而气泡是需要相对视口定位的。我最初直接用getBoundingClientRect()返回的坐标去定气泡位置结果在页面滚动或缩放后气泡要么悬在半空要么被卷出屏幕外。排查过程花了一个下午。我把getBoundingClientRect的坐标、阅读器容器内部的scrollTop、PDF 页面的transform缩放值都打了出来对照才确认气泡定位必须监听滚动事件在选区坐标被更新时立刻重新计算。最终方案是给 PDF 阅读器的滚动容器挂一个scroll监听滚动发生时隐藏气泡停止滚动后再按缓存选区位置重新弹出。实际操作中更稳妥的做法是让气泡跟随一个动态插入的锚点元素。把选区的坐标换算成相对锚点的偏移然后用浮动层来包裹这样即使滚动了只要锚点位置更新气泡就能跟着移动。4.2 快速连续划词时翻译结果“张冠李戴”气泡错乱的问题在前面已经提到了根因——响应乱序。我用requestSeq解决了渲染覆盖问题但在实际测试中还有一层更隐蔽的坑。用户选中一段文本后可能还没等翻译响应又去复制同一段文本或继续滚动。此时mouseup事件会被重复触发同一个文本可能短时间内被翻译两次。解决方案是加了一个简单的“重复请求抑制”逻辑如果新选区的文本和上次选中完全一样且上次请求还没返回就直接复用旧请求的 Promise不发第二次。判断条件用text rect 坐标拼出来的 key 去缓存 Promise这个 key 也能顺手作为翻译缓存的一部分。4.3 插件卸载与页面切换后的残留 UI插件开发初期我频繁地改代码并重新加载插件很快发现一个尴尬现象气泡 DOM 在插件卸载后还留在了页面上。有时切换到别的页面角落里还悬浮着上一个插件的翻译结果。Logseq 插件机制不会在你卸掉插件时自动去清理 iframe 里手动挂载的 DOM 节点。所以必须在插件的清理函数里显式移除所有动态节点。我的做法是给每个动态生成的元素打上>function cleanup() { document.querySelectorAll([data-logseq-pdf-translator]).forEach((node) node.remove()); }同时函数的外层还要处理 Logseq 侧边栏 UI 的变化。如果用户关闭了侧边栏气泡需要能感知并隐藏否则继续浮在已经不存在的内容区上体验极差。我通过ui:visible:changed事件监听侧边栏可见性变化在不可见时立即移除所有气泡。5. 打磨到“能每天用”的细节清单5.1 缓存设计为什么必须做以及怎么做翻译接口都有额度限制而论文阅读场景中频繁遇到同一段落被反复划词的情况。如果每次划词都重新请求既浪费额度也让插件变得迟钝。缓存是让插件“能每天用”的关键。我的缓存 key 设计是原文哈希 目标语言 provider名三者的组合。哈希直接用简单字符串哈希函数计算原文避免把整段英文作为 key 存进存储。缓存值包含译文、时间戳、来源 provider。默认缓存有效期设为 7 天过期自动清理。存储位置我选了一开始让很多人争议的localStorage。插件运行在 iframe 里localStorage的隔离规则和浏览器页面不完全一致实际测试下来在 Logseq 插件环境是可用的。选择它而不是写文件是因为写文件会不停触发 Logseq 的数据库索引增加不必要负担。localStorage虽然简单配合 7 天过期策略在单机场景已经非常好用。5.2 命令面板、快捷键与工具栏入口一个插件如果只能靠鼠标划词触发使用效率会打折扣。我注册了三个命令面板入口PDF Translator: 翻译当前选区绑定modshifttPDF Translator: 收集翻译到笔记绑定modshiftyPDF Translator: 打开设置命令面板的好处是操作路径统一。如果用户不记快捷键也可以用/唤起命令面板输入关键字。我特意把快捷键统一在 global 模式下注册这样光标停在 PDF 阅读器里时快捷键也能被正确捕获。工具栏入口方面我在 Logseq 右侧边栏注册了一个小按钮点击后可以直接启用或停用划词翻译模式。默认是启用状态关闭后一切鼠标选区监听都不再触发以防用户只想专注圈选做摘录时被翻译弹窗干扰。5.3 设置面板让用户自己选 provider 和语言设置面板虽小却是决定插件适用范围的关键。我利用logseq.useSettingsSchema配置了以下字段字段类型说明provider下拉选项选择翻译服务OpenAI 兼容接口 / 通用翻译接口 / 自定义apiKey密码框对应 provider 的鉴权密钥baseUrl文本框支持自建服务的自定义地址targetLang下拉选项译文目标语言中文、英文、日语等bubbleTimeout数字气泡自动消失时间默认 1500msenabled布尔开关总开关默认开启设置面板的 schema 定义好之后Logseq 会自动渲染出配置界面插件侧只需要在设置变更时重新读取并更新运行配置。这里有个细节apiKey用了密码类型后插件读取到的是明文还是脱敏值不同版本的行为有差异。我的处理是提供一个“测试连接”按钮让用户在保存前验证密钥是否可用省得翻译到一半才发现鉴权失败。6. 发布到 Logseq 插件市场之后的事6.1 打包发布与 marketplace 提交插件开发完成下一步就是让更多人用上。Logseq 插件市场的发现机制要求仓库满足几个条件仓库名必须是用户名/插件名的形式manifest.json里要有完整的title、description、effect字段release 版本号要符合语义化规范。提交过程比想象中简单在 GitHub 上创建仓库并推代码写一份清晰的 README 说明安装方式和配置步骤然后发布一个 tag。官方插件市场通过marketplace.json收录符合要求的仓库提交 PR 后等待合并即可。如果只想自用直接在 Logseq 插件页填写仓库地址也能加载。6.2 真实反馈中最集中的两类问题插件发布后我在社区收到了一些反馈。相比功能请求更多用户提到的是两类实际问题。第一类集中在“切换 PDF 页面后气泡不消失”。原因其实是我在捕捉选区时没有检查页面切换事件导致旧气泡残留在新页面上。修复方式是监听 PDF 阅读器的页面切换回调在切换时主动触发cleanup()。第二类是“有些长段落翻译不完整”。通用翻译接口对超长文本有限制而论文段落经常超过几百字。我的处理是加入文本拆分逻辑按句子边界拆成小段分别请求后再拼接。这带来了另一个问题——拆分请求会消耗更多额度。权衡后我在设置里加了一个选项默认“自动按段落拆分”用户可以改成“单次请求不拆分”。6.3 我后续准备怎么迭代基于用户反馈下一步迭代方向已经比较明确一是增加可自定义的术语表让专业术语的翻译保持一致二是支持“整篇论文摘要翻译”只翻译每段第一句帮用户快速扫读文献三是把翻译记录导出成 CSV 或 Markdown 文件方便进一轮系统化整理。我个人的体会是一个好的 PDF 翻译插件本质是“降低阅读摩擦”。它不该让用户停下来想“怎么翻译”而是让翻译变成一种自然的本能动作就像手指划过纸面就自动浮现译文一样。这个项目目前已经能稳定支撑我每天的文献阅读如果你也经常在 Logseq 里啃 PDF不妨把它当成一个参考或者直接改造出更契合自己习惯的版本。