PageWeave：本地 PDF 翻译桌面工具
PageWeave：本地 PDF 翻译桌面工具
星染PageWeave：本地 PDF 翻译桌面工具
读英文论文、技术文档时，最烦的不是看不懂，而是译完版式全毁——图片跑位、表格错乱、公式变乱码。云端翻译服务又要把 PDF 上传出去，敏感材料心里不踏实。
于是做了 PageWeave：一个 Windows 本地 PDF 翻译桌面应用。拖入 PDF，选语言和 AI 服务商，输出尽量保留原排版的译文。
1. 它解决什么问题
常见 PDF 翻译链路大致两类：
| 方式 | 优点 | 痛点 |
|---|---|---|
| 云端网页/App | 开箱即用 | 上传隐私风险、排版常崩、依赖网络 |
| 纯 CLI（如 BabelDOC） | 能力强、可脚本化 | 装 Python、配环境、记参数，门槛高 |
PageWeave 想做的是中间那一层：
- 能力：接 BabelDOC，尽量保留图片、表格、段落结构
- 体验：Tauri 桌面壳，拖拽、进度、日志、取消、打开结果
- 本地：引擎以内置 sidecar 分发，用户不用装 Python
- 可配：多服务商 OpenAI-compatible API，Key 只存在本机
一句话：把「能用的 CLI」包成「愿意天天用的桌面工具」。
2. 核心功能
| 模块 | 能做什么 |
|---|---|
| PDF 翻译 | 拖拽/选择 PDF，源/目标语言，服务商与模型，实时进度与日志，取消，完成后打开文件/文件夹 |
| 输出模式 | 仅译文 / 原文+译文双语对照 / 全部输出 |
| 高级参数 | 页码范围、术语表 CSV、OCR 模式、并发池、自定义 system prompt 等 |
| 转 Markdown | 本地 PDF / DOCX / PPTX / XLSX / XLS → .md（基于 markitdown，不依赖 API Key） |
| AI 配置 | 增删改服务商，测试连接，拉 /models，导出配置（默认不含 Key） |
| 任务与设置 | 任务状态与最近日志；主题/语言、默认目录与服务商、离线资源包、自动更新 |
内置预设包括 OpenAI、DeepSeek、硅基流动、阿里云百炼、Moonshot、智谱，以及 Ollama / LM Studio 等本地兼容端点。
3. 架构怎么拆
技术栈大致是：
| 层级 | 技术 |
|---|---|
| 桌面 UI | Tauri 2 + React 19 + TypeScript + Ant Design + Zustand + i18next + Vite |
| 本地后端 | Rust：文件选择、子进程、SQLite 配置、任务事件 |
| 密钥 | Windows Credential Manager（DPAPI），库里只存 api_key_id 引用 |
| 翻译引擎 | BabelDOC sidecar（PyInstaller 冻结） |
| 转换引擎 | markitdown sidecar，与翻译链路平行，可单独剥离 |
关键设计点有三个。
3.1 Sidecar，而不是让用户装 Python
MVP 阶段用「Rust 调 CLI 子进程」最省事；分发时再把 BabelDOC / markitdown 冻成独立可执行文件，通过 Tauri 的 externalBin + resources 打进安装包。
用户侧感知就是：装完就能用，首次翻译前在设置里装一下 BabelDOC 离线资源包（模型 + 字体）。
3.2 API Key 不落明文
- Key 进系统凭据库（DPAPI 加密）
- SQLite 只存引用
- 导出配置默认剥离 Key
- 日志对
sk-...一类 token 做掩码
个人工具也值得把密钥路径做干净，后面才敢放心配各种服务商。
3.3 翻译与转 Markdown 解耦
转 Markdown 走独立 sidecar，不走翻译管线。需要「整本 PDF 先变成可编辑 Markdown」时直接用；不需要的人也可以在构建层面剥离，不拖翻译主路径。
4. 一次典型使用流程
- 打开应用，在 AI API 配置 里加服务商（或用预设），填 Base URL / Key / 模型，点测试连接
- 设置 里确认默认输出目录、默认语言；首次翻译前安装离线资源包
- 翻译 页拖入 PDF，选源/目标语言、输出模式、服务商与模型
- 开始翻译，看进度条和实时日志；可随时取消
- 完成后「打开文件」或「打开所在文件夹」
需要术语统一时，在翻译参数里导入 CSV 术语表；扫描件/复杂 PDF 可开 OCR 相关选项。
开发者本地跑：
1 | pnpm install |
环境要求：Node ≥ 20、pnpm ≥ 9、Rust（rustup + stable + MSVC）。sidecar 需单独构建，不随 tauri dev 自动生成。
5. 为什么选这套技术
- Tauri 2：体积和内存比 Electron 友好，系统能力（对话框、凭据、更新）够用
- React + Ant Design：配置页、表格、表单写起来快，适合工具型 UI
- Zustand：翻译任务、服务商、设置状态分 store，事件流也好挂
- BabelDOC：版式保留是刚需，自己从零做 PDF 重排不现实
- AGPL-3.0：集成 BabelDOC 后整体开源，项目本身也按 AGPL-3.0-or-later 发布
参考过 ai-toolbox 的服务商配置体验，以及 BabelDOC 的 CLI/API 形态，但没有照搬业务代码——桌面壳、密钥、任务流和 markitdown 并行能力是自己长出来的。
6. 边界与后续
当前明确不做（或只做很浅）的部分：
- 云同步、账号体系、在线支付
- 复杂任务队列与批量编排（单文件/少量文件够用）
- DOCX/PPTX 的「保留版式翻译」（Markdown 转换有，版式级翻译没有）
- OCR 的深度专项优化
后续更想打磨的是：安装与首次资源包体验、失败重试与错误可读性、更多本地模型场景下的默认参数，以及更新通道的稳定性。
7. 小结
PageWeave 的定位很具体：
Windows 上，本地跑，API 自己配，PDF 尽量保住版式。
如果你也受够了「译完面目全非」或「必须上传才能译」，可以试试：
欢迎提 Issue / PR。有真实 PDF 翻车样本也特别有价值——版式翻译的坑，往往只在具体文件里才会露出来。
