folio-pdf-translate
Optional external translation backend: when explicitly selected with service="google" (CLI: --service google), the engine translates the extracted PDF text through Google Translate to produce the bilingual/mono output, with hover highlighting disabled.
Optional external translation backend: with service="ollama" the server routes the extracted PDF text to a locally running Ollama model for translation instead of having the calling agent supply translations, with hover highlighting disabled.
Optional external translation backend: with service="openai" the server sends the PDF's text batches to the OpenAI API for translation, reading credentials from an existing environment variable mapped via secret_env; hover highlighting must be turned off in this mode.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Folio PDF Translate
本项目基于 Alonemo-Nnqc/Folio 二次开发,提取其 PDF 翻译引擎,配套本地 MCP 和 Agent Skill。主要面向 Windows,兼容 macOS。无需安装 Folio 应用。
当前 Agent 翻译可选中文字的英文 PDF,引擎保护原公式字形并排版,输出原文在左、译文在右的双语 PDF。默认包含面向 Adobe Acrobat 桌面版的双向悬浮高亮。公式和图片不参与高亮,文字保持可选,不增加覆盖正文的 Link/Widget。
致谢与项目来源
感谢 Alonemo-Nnqc 及 Folio 贡献者开源 PDF 解析、翻译、公式保护与排版实现。本项目的 Swift 和 C# 引擎基于这些代码提取和修改,并非从零实现。
本项目在此基础上增加独立构建、本地 MCP、Agent Skill、当前 Agent 翻译流程、双语 PDF 双向悬浮高亮及分类修复。这是独立维护的二次开发项目,不是 Folio 官方发行版。欢迎访问和支持原项目:Alonemo-Nnqc/Folio。
提取提交、代码范围和修改记录见 UPSTREAM.md。原作者版权声明和许可证完整保留于 LICENSE,第三方组件说明见 THIRD-PARTY-NOTICES.md。
Related MCP server: Neyvia PDF Studio
让 Agent 安装
将仓库下载到准备长期保留的目录,在具有本机终端权限的 Agent 客户端中打开目录,发送:
请读取 README.md 和 AGENT_INSTALL.md,检查当前电脑的依赖,安装缺少的环境,构建并验证引擎,将 folio-pdf-translate MCP 和 Skill 安装到我当前使用的 Agent 客户端。复用符合要求的环境,保留其他客户端配置。完成后验证客户端能识别 MCP 工具和 Skill。只有需要我操作系统弹窗、登录或重新连接客户端时,再告诉我具体操作。
AGENT_INSTALL.md 提供 Windows/macOS 分流、依赖补齐、构建、客户端配置及验收步骤。Agent 应执行这些步骤,而不是把命令清单交回用户。scripts/setup.ps1 / scripts/setup.sh 负责 Python 包和引擎构建;系统依赖及客户端接入由安装 Agent 按指南完成。系统权限和客户端能力可能需要少量人工操作。
支持范围
输入:具有可选文字、未加密的 PDF。当前流程不提供扫描件 OCR。
默认
service="agent":调用 MCP 的 Agent 负责逐句翻译,不需要额外翻译 API Key,不另起 Agent CLI。模型服务、联网和费用取决于 Agent 客户端。输出:双语 PDF、纯译文 PDF、普通双语 PDF、源文分类报告和高亮覆盖报告。无 HTML 输出。
作者信息、参考文献、出版信息、图内标签默认保留原文;标题、正文、关键词、列表及算法自然语言参与翻译。
公式使用原 PDF 字形,位置可能随排版调整。需要检查上下标、矩阵、遮挡及遗漏,不能承诺任意 PDF 都能无损排版。
悬浮需 Adobe Acrobat 桌面版允许 Acrobat JavaScript;默认单页视图。其他阅读器可正常预览,不承诺执行悬浮。Adobe 的实际悬浮、拖选复制和离开窗口清除需验收。
macOS 与 Windows 使用相同 MCP 参数,按 MCP 进程的操作系统自动选择 Swift 或 C# 引擎。不支持 Linux。
依赖
项目 | Windows | macOS |
系统/架构 | 默认 | 引擎最低 macOS 14;构建主机还须能运行所选 Swift/Apple SDK |
Python | CPython 3.11+,含 pip 和 venv,加入 PATH | CPython 3.11+,命令为 |
构建工具 | .NET 10 SDK;PowerShell | Swift 6.2+、配套 Apple SDK/Command Line Tools 或 Xcode; |
中文字体 | 宋体/微软雅黑,或引擎支持的 Noto CJK、思源字体 | 宋体/苹方等系统字体 |
Agent | 支持本地 stdio MCP、能领取并回填待译批次的客户端;Skill 安装方式由客户端决定 | 同左 |
交互阅读器 | Adobe Acrobat 桌面版,仅用于查看悬浮效果;生成 PDF 不依赖 Adobe | 同左 |
Python 直接依赖:mcp==1.28.1、PyMuPDF==1.28.2。requirements.lock 锁定直接/间接依赖、平台条件和下载文件哈希,并包含构建后端 setuptools==80.9.0。安装脚本用 pip 校验哈希,不依赖 uv。
Windows 原生直接依赖在 engine-windows/PDFTranslateEngine.csproj 中固定:PdfPig 0.1.16、SkiaSharp 3.119.4、SkiaSharp.HarfBuzz 3.119.4。NuGet 自动还原间接依赖及本机库。macOS 使用 PDFKit、CoreGraphics、CoreText 等系统框架,无外部 Swift Package 依赖。
首次安装需访问 PyPI、NuGet 及所需 SDK 下载源。默认翻译不需要 GPU、本地模型、Node.js、LaTeX、Poppler、Pillow 或浏览器。Node.js 只用于 JavaScript 模拟测试;没有 Node.js 时该项测试会跳过。自制 PDF 样例已提交,不需要安装 LaTeX 重建。
从源码安装
下载仓库 ZIP 后解压,或用 Git 克隆。以下命令都在含本 README 的项目根目录执行。安装会创建 .venv 和本机引擎,不修改 Agent 客户端配置。
Windows
先确认 python --version、dotnet --version 可运行,且满足上表版本要求。
./scripts/setup.ps1若 PowerShell 阻止本次本地安装脚本,可仅为此次进程指定执行策略,不修改全局设置:
powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/setup.ps1默认构建 win-x64。显式 ARM64 构建:./scripts/setup.ps1 -Runtime win-arm64;还需确认所用 Python/PyMuPDF 提供匹配架构的安装包,此组合尚未验证。
macOS
检查 python3 --version、swift --version、xcrun --show-sdk-path。缺少 Apple 工具时先安装或更新 Command Line Tools/Xcode;旧版本工具不一定满足 Swift 6.2。
sh scripts/setup.sh脚本拒绝复用允许全局包的 .venv。遇到该提示,将原 .venv 改名保留后重新安装。正常新安装不读取全局 Python site-packages。
安装后的文件
平台 | Python | 引擎 |
Windows |
|
|
macOS |
|
|
必须保留完整项目目录。仅 pip install . 只安装 Python 服务,不构建或携带原生引擎、Skill,不能作为完整安装方式。
配置 MCP 和 Skill
安装完成后生成当前目录的 MCP 配置,Windows 使用:
./.venv/Scripts/python.exe scripts/print_mcp_config.pymacOS 使用:
./.venv/bin/python scripts/print_mcp_config.py输出是通用 mcpServers JSON。支持此格式的客户端可合并该条目;使用其他格式的客户端,填写相同的服务器名称 folio-pdf-translate、command 和 args。路径由脚本根据本机目录生成,不需要复制作者电脑的路径。不要把生成的本机配置提交到公共仓库。
启动程序 scripts/launch_mcp.py 会切换到项目目录,并调用项目 .venv。不需要依赖客户端的工作目录。根目录 plugin.json、mcp.json 是可选插件元数据;${PLUGIN_ROOT} 只适用于支持该变量的宿主,不是所有 MCP 客户端通用的配置。该元数据的 command="python" 还要求宿主 PATH 中有可用的 python;常规安装应使用 print_mcp_config.py 生成的项目 Python 绝对路径,不能仅导入元数据就视为安装完成。
将 skills/folio-pdf-translate/ 整个文件夹安装到客户端支持的 Skill 目录,或通过客户端从仓库安装该目录。Skill 指导调用流程,不包含引擎;MCP 和 Skill 都需要配置。移动项目目录后应重新生成 MCP 配置,并重新建立连接。
使用
向已配置的 Agent 提交 PDF,例如:
使用 folio-pdf-translate 全文翻译这篇论文。原文在左,中文在右,保留公式和图片,生成带双向悬浮高亮的 PDF。检查关键词、标题、列表、算法说明和所有排除项。
Agent 依次调用:
start_translation(input_path, output_directory),默认service="agent"、hover_highlight=true。get_pending_translations(job_id),自行翻译每个句子,结合paragraph_source理解上下文。submit_translations(job_id, request_id, translations),按原 ID 回填,逐字保留{vN}和出现次数;不跨 ID 合并或移动译文。循环领取/提交,查询
get_translation_status,直到state="completed"。waiting_for_translation表示等待 Agent,building_hover表示尚未完成交互层。检查输出和报告,再交付 PDF。
pages="1,3-5" 用于试译;其余页保留原文。全文翻译省略 pages。用户取消时使用 cancel_translation。新任务创建独立输出目录,不覆盖源文件。
artifact | 内容 |
| 默认交付的双语悬浮 PDF |
| 启用悬浮时保留的普通双语 PDF |
| 纯译文 PDF |
| 全部已分析文本块的页码、原文、分类和是否翻译 |
| 高亮对应关系、保护区域和未能定位的排除项 |
高亮覆盖统计只针对已翻译文本,不证明全文没有漏译。必须对照源 PDF 检查 coverage_report 的排除项。无法准确定位的文本保持可阅读,记录在 hover_report.skipped,不猜测高亮位置。
CLI(MCP 不可用时)
以下示例中的 python 应替换为上表中的项目 Python:
python -m server translate INPUT.pdf --output-dir output --service agent
python -m server agent-pending --exchange-directory EXCHANGE_DIRECTORY
python -m server agent-submit --exchange-directory EXCHANGE_DIRECTORY --request-id REQUEST_ID --translations-file TRANSLATIONS.json第一条命令保持运行;另一个终端/工具调用领取并回填。TRANSLATIONS.json 为 ID 到译文的 JSON 对象。CLI 不会自行产生 Agent 译文,等待状态不是卡死。支持 --pages、--from、--to、--glossary-file;完整参数见 python -m server translate --help。
只有明确选用外部服务时才传入 google、bing、openai、openaicompatible、ollama 或 deepseek,同时设置 hover_highlight=false(CLI:--no-hover-highlight)。凭证用 secret_env 映射已有环境变量,不写入 Skill、命令参数或公共配置。Agent 模式失败不会自动切换外部服务。
验证与维护
python -m pip check
python scripts/verify_install.py
python -m unittest discover -s tests -v这里也应使用项目 Python。verify_install.py 使用自制输入、固定测试译文,通过真实 stdio MCP 完成原生引擎到悬浮 PDF 的流程,不调用翻译 API,不代表模型翻译质量评测。测试在临时目录运行;不需要用户论文。
验证边界和本次实际结果见 VALIDATION.md。Windows workflow 已提供,但未运行的 CI 不能视为 Windows 已通过。实际 Adobe 交互不能由 PDF 结构检查或模拟 JavaScript 测试替代。
更新 Python 依赖时修改 pyproject.toml / requirements-build.in,使用维护工具 uv 重新生成锁文件,并在干净环境测试:
uv pip compile pyproject.toml requirements-build.in --universal --python-version 3.11 --generate-hashes --output-file requirements.lock不要直接复制开发机的全局 pip freeze。NuGet 直接依赖版本固定在项目文件;当前未锁定其完整传递依赖图。平台构建包应在目标系统测试后放 GitHub Releases,不提交源码仓库。Windows 自包含发布必须包含整个 bin/windows/,运行者无需另装 .NET Runtime;macOS 必须同时携带 .bundle 资源。两者仍需要 Python 环境及 Agent 客户端。
仓库内容与许可
源码目录包括 server/、engine/、engine-windows/、skills/、scripts/、tests/ 和 examples/。仅保留自制 examples/formula-sample.pdf;不包含个人论文、译文、日志、虚拟环境或构建产物。.gitignore 排除这些文件,但不能代替发布前检查。Python 锁文件、NuGet 项目文件、资源和第三方声明应一起上传。
来源和修改范围见 UPSTREAM.md,上游 Folio 的 MIT 声明见 LICENSE,组合依赖说明见 THIRD-PARTY-NOTICES.md。PyMuPDF/MuPDF 使用 AGPL 或商业许可,保留 MIT 文件不表示整个组合包只受 MIT 约束。发布或再分发时需遵守实际组件的许可。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Translate text PDFs, keep the layout, get bilingual PDFs. MCP: EN/ZH. Website: 92 languages.
Translate PDFs and scans into another language in the same layout, every number kept. PDF to Word.
Translate PDFs, scans, Office files and EPUB across 475 languages and styles, preserving layout.
Translate a user's uploaded text-based PDFs while keeping the layout, check job status, and fetch temporary links to translated or bilingual PDFs. Through MCP, the target language is English or Chinese; the iSomor website supports 92 target languages. OAuth 2.0 with PKCE; the user's iSomor account credits apply. Text-based PDFs only; scanned PDFs, including OCR'd scans, are not supported.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to extract structured data from PDFs with confidence scores and provenance, and to search, review, and correct documents via MCP tools, resources, and prompts.-
- AlicenseNot gradedqualityCmaintenanceInteractive PDF workspace shared by a human operator and an AI agent, enabling navigation, search, text extraction, annotations, form filling, and save actions via a PDF.js viewer.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to edit text inside real PDF files in place while preserving fonts and layout, with a before/after preview. Also supports compressing, merging, splitting, converting, translating, generating and querying PDFs through a hosted remote MCP endpoint.MIT
- AlicenseBqualityBmaintenanceEnables AI coding agents to inspect digital or scanned PDF forms and worksheets, map detected answer slots through a virtual Excel/Set-of-Marks view, and inject baseline-snapped text, multi-line answers, or option marks into clean output PDFs. Supports visual verification of completed pages.6MIT