插件功能问题

关于翻译选项、OCR、功能说明等问题。

---

Scanned PDF detected, 翻译失败 🔥

问题描述

翻译时提示 "Scanned PDF detected, 翻译失败"。

原因

pdf2zh 和 pdf2zh_next 不直接提供文档 OCR 功能。您需要用其他工具对扫描版文件进行 OCR 处理，再调用插件的翻译功能。

解决方案

方案 1：对 PDF 进行 OCR 处理

使用其他工具对扫描版 PDF 进行 OCR：

1. Adobe Acrobat

   • 打开 PDF → 编辑 PDF → 识别文本

2. ABBYY FineReader

   • 专业的 OCR 软件

3. 在线 OCR 服务

   • 各种在线 PDF 转 Word 再转 PDF 的服务

4. 命令行工具

   # 使用 ocrmypdf
   ocrmypdf input.pdf output.pdf

方案 2：开启 OCR 临时方案

在 Zotero 插件配置中：

1. 确保 "自动开启 OCR 临时方案" 选项已开启
2. 如果还是失败，尝试开启 "兼容模式"

注意

OCR 选项并不是直接提供 OCR 服务，它只是一个对于 OCR 后的文件进行兼容的临时方案。

方案 3：手动处理

将扫描版 PDF 转换为可搜索的 PDF 后，再使用插件翻译。

---

OCR 模式与兼容模式是什么？

问题描述

pdf2zh_next 服务中的 OCR 模式与兼容模式是指什么？应该怎么选择？

原因

这两个选项是为了处理不同类型的 PDF 文件而设计的。

解决方案

OCR 模式

• 作用：不直接提供 OCR 服务，而是对 OCR 后的文件进行兼容
• 使用场景：当您的 PDF 已经做过 OCR 处理时
• 建议：保持"自动开启 OCR 临时方案"选项开启

兼容模式

• 作用：生成的文件兼容性更好，但文件大小会更大
• 使用场景：非必要情况不需要开启
• 建议：如果您翻译功能正常，但某一次失败了（并且确定不是远程翻译服务的问题），可以尝试开启

选择建议

• 正常情况：OCR 方案开启，兼容模式关闭
• 翻译失败（非服务问题）：尝试开启兼容模式

---

裁剪 PDF 时内容被截断

问题描述

使用"裁剪 PDF"功能时，部分内容被截断了。

原因

默认的裁剪偏移量可能不适合某些 PDF。

解决方案

调整 server/utils/config.py 中的 config.pdf_w_offset 值：

1. 打开文件：server/utils/config.py
2. 找到 pdf_w_offset 配置项
3. 降低该值（例如从 50 降到 30）
4. 保存文件并重启 server.py

# config.py 示例
config.pdf_w_offset = 30  # 默认值可能更高，降低这个值

注意

• 值越小，裁剪越保守（可能保留更多空白）
• 值越大，裁剪越激进（可能截断内容）
• 建议逐步调整，找到合适的值

---

双栏 PDF 翻译效果不好

问题描述

双栏论文翻译后效果不好，或者格式混乱。

原因

普通翻译模式不适合双栏 PDF。

解决方案

使用 双语对照(裁剪) 选项：

1. 右键点击双栏 PDF
2. 选择「PDF2zh → 双语对照(裁剪)」
3. 此选项会：
   • 先将 PDF 竖向裁剪为单栏文件
   • 再左右拼接原文和翻译

说明

"双语对照(裁剪)"功能仅针对双栏 PDF 论文设计。

---

各种翻译选项有什么区别？

问题描述

不知道该选择"翻译 PDF"、"裁剪 PDF"、"双语对照"还是"双语对照(裁剪)"。

原因

不同选项适用于不同的使用场景。

解决方案

翻译 PDF (Translate PDF)

• 适用场景：大多数情况
• 效果：生成纯翻译后的 PDF
• 文件类型：替换原文或生成新文件（取决于设置）

裁剪 PDF (Crop PDF)

• 适用场景：手机阅读、需要裁剪边距
• 效果：在宽度 1/2 处裁剪，上下拼接
• 注意：会将页面两侧空白处裁剪，可能截断内容

双语对照 (Compare PDF)

• 适用场景：需要对照原文和翻译
• 效果：左边原文，右边翻译
• 等同于：pdf2zh_next 引擎 + 双语模式 Left&Right

双语对照(裁剪) (Crop-Compare PDF)

• 适用场景：双栏论文需要对照
• 效果：先竖向裁剪为单栏，再左右拼接
• 最适合：双栏学术论文

选择建议

需求	推荐选项
纯阅读翻译	翻译 PDF
手机阅读	裁剪 PDF
学习/对照	双语对照
双栏论文对照	双语对照(裁剪)

---

批量翻译失败

问题描述

多选条目进行批量翻译时，部分或全部失败。

原因

1. 并发数设置过高
2. 网络问题
3. 某些 PDF 有问题

解决方案

1. 降低并发数

   • 在插件设置中降低 QPS 和 Pool Size
   • 或者分批次翻译

2. 检查失败的 PDF

   • 单独翻译失败的 PDF 查看具体错误
   • 可能是扫描版或格式问题

3. 查看终端日志

   • 查看具体哪个文件失败及失败原因

---

自定义字体不生效

问题描述

在 pdf2zh 引擎中配置了自定义字体，但没有生效。

原因

1. 远程服务器部署时，插件无法访问本地字体文件
2. 字体路径配置错误

解决方案

本地部署

1. 确保字体文件路径正确
2. 路径必须是本地绝对路径
3. 确保字体文件存在且可读

远程部署

如果采用远端服务器部署，暂时无法使用插件界面的自定义字体配置，需要手动修改配置文件：

1. 打开服务器上的 config.json 文件
2. 找到 NOTO_FONT_PATH 字段
3. 修改为服务器上的字体路径
4. 重启 server.py

{
  "NOTO_FONT_PATH": "/path/to/your/font.ttf"
}

---

额外配置参数怎么用？

问题描述

不知道"额外配置参数"该怎么填写。

原因

额外配置参数用于设置不同服务的特定参数。

解决方案

基本规则

额外配置参数名需要与配置文件中的字段相同。

示例：pdf2zh_next 的 openai 参数

在额外配置中填写：

openai_temperature=0.3
openai_send_temperature=true

这些参数与 config.toml 文件中的字段相对应。

详细文档

更多关于额外配置的信息，请参考 extraData.md

常见参数示例

服务	参数名	说明
openai	temperature	控制随机性，0-1 之间
openai	top_p	核采样参数
deepseek	temperature	控制随机性

---

生成的 PDF 在某些阅读器显示异常

问题描述

翻译后的 PDF 在某些阅读器中显示格式异常。

原因

不同 PDF 阅读器对 PDF 规范的支持程度不同。

解决方案

1. 更换阅读器

   • 尝试使用 Adobe Acrobat Reader
   • 或其他主流 PDF 阅读器

2. 更换引擎

   • 尝试切换 pdf2zh 和 pdf2zh_next 引擎

3. 更换生成模式

   • 尝试不同的翻译选项（如从"翻译 PDF"改为"双语对照"）