展开本页目录
开始前准备什么
- 下载到独立练习目录，先运行材料校验，再连接自己的翻译服务。
- 准备 Python 与对应工具的隔离环境；PDF 检查使用 Poppler，翻译版本分别记录。
- 原文均为原创练习材料；密钥只填在本机，不写入下载文件或截图。
- 准备独立测试库
- 导入条目并挂原文
- 配对安装插件与 Server
- 启动后端并设置连接
- 先翻译单个测试附件
- 核对译文附件挂载
- 核对文件与库关系两层证据
原创 PDF/CSV/EPUB/HTML、逐步说明、校验脚本与真实离线记录；不含模型译文。
对应本页操作、工具边界与验收范围。
本页截图使用的原始文档。
读取真实材料与文件结构；不请求模型、不读取凭证。
当前材料与脚本的实际运行结果。
本页专用练习材料；运行范围见 README。
本页专用练习材料；运行范围见 README。
1. 准备独立测试库
下载 item.json 与 source.pdf，在 Zotero 新建“QR PDF2zh 练习”分类。item.json 为原创 CSL JSON 条目，不含真实 DOI；先在独立测试库导入，避免动到自己的正式资料库。
bash
python3 verify.py
2. 导入条目并挂原文
在 Zotero 文件菜单导入 item.json，把 source.pdf 拖到刚导入条目下。展开条目检查附件层级，双击打开原文。下载包 attachments.tsv 是预期清单，不是假冒 Zotero 数据库导出。
3. 配对安装插件与 Server
从官方最新 release 同时取得 XPI 与 Server，记录两个版本。官方 v4.1.7 强调二者同时更新；具体支持的 Zotero 版本以当前 release 为准。不要用截图版本猜本机版本。
4. 启动后端并设置连接
按官方 Server 说明启动服务，在 Zotero 插件设置里填实际 Server 地址，选择 pdf2zh 或 pdf2zh_next 对应引擎，再配置本机可用的服务。官方截图用于定位设置与入口。
5. 先翻译单个测试附件
右键选中 source.pdf，使用插件对应翻译菜单。保留进度和错误信息，等待后台任务完成；本教材没有运行 Zotero 插件或翻译模型，截图来自项目官方示例。
6. 核对译文附件挂载
展开原条目，确认原 PDF 仍在，译文/双语附件在同一条目下可打开。远程/Docker 模式可能通过 HTTP 挂载附件，检查实际文件可访问性；不能只看进度到 100%。
7. 核对文件与库关系两层证据
运行包内离线脚本检查原文哈希与清单，再在 Zotero 界面人工核对条目和附件关系。文件存在检查没有访问 Zotero 数据库，也不能证明插件已完成。
bash
python3 verify.py
怎样确认已经完成
- 原条目与 source.pdf 相连，原文哈希保持不变。
- 插件和 Server 版本配对，翻译任务失败时保留错误而不生成假附件。
- 译文实际挂到同一条目且能打开；教材清单不冒充数据库实测。
常见问题
100% 了却没有译文附件怎么办？
先检查 Server 日志、实际输出路径和 HTTP 可访问性，再检查插件版本是否配套。任务完成与附件挂载是两个环节。
练习包能自动检查我现有 Zotero 库吗？
不能，也不会读取你的库。脚本只检查解压目录中的原创材料；条目与附件关系需要在自己的测试库实际确认。