Zotero Deeplx API 配置后无法触发自动翻译？

Question

Zotero Deeplx 插件配置后无法触发自动翻译，常见原因在于 API 地址与端口设置错误或服务未就绪。典型问题包括：① 本地运行的 DeeplX 服务（如 `deelplx` 或 `deeplx-api`）未启动，或监听端口（默认 5000/8080）被防火墙/其他进程占用；② Zotero 插件中填写的 API URL 格式不正确（如遗漏 `http://`、误用 `https`、多加 `/v1/translate` 后缀）；③ DeeplX 版本过旧（v2.0+ 才支持标准 OpenAI 兼容接口），而插件依赖该协议；④ Zotero 插件权限未启用“自动翻译”开关，或仅对 PDF 元数据生效而未勾选“摘要/标题/作者”等字段；⑤ 中文系统区域设置导致编码异常，引发请求静默失败。建议通过浏览器直接访问 `http://127.0.0.1:5000/health` 验证服务状态，并在 Zotero「首选项→插件→Deeplx」中开启调试日志，观察控制台报错（如 404、502、timeout），再针对性排查网络连通性与 JSON 响应格式兼容性。

Answer 1

```html

一、现象层：Zotero Deeplx 插件“静默失效”的典型表征

用户点击文献条目无反应、右键菜单缺失“Translate”选项、PDF元数据更新后摘要/标题仍为原文——这些并非插件崩溃，而是请求链路在某环节被静默截断。不同于报错弹窗，该问题常表现为“零反馈”，易被误判为功能未启用。尤其在中文 Windows 系统中，区域设置（如 GBK 编码）与 UTF-8 JSON 请求头冲突时，DeeplX 服务可能直接拒绝解析，返回空响应而非 HTTP 错误码。

二、连接层：本地服务可达性验证（端到端连通性诊断）

1. 终端执行：curl -v http://127.0.0.1:5000/health 或浏览器访问 http://127.0.0.1:5000/health；
2. 若返回 {"status":"ok"} → 服务存活；返回 Connection refused → 检查进程：ps aux | grep deeplx（Linux/macOS）或 netstat -ano | findstr :5000（Windows）；
3. 若端口被占用（如 PID 1234），执行 kill -9 1234 或 taskkill /PID 1234 /F；
4. 确认防火墙放行：sudo ufw allow 5000（Ubuntu）或 Windows Defender 高级设置中添加入站规则。

三、协议层：API 地址与接口规范的精确对齐

配置项	正确示例	常见错误	后果
基础 URL	http://127.0.0.1:5000	https://127.0.0.1:5000、127.0.0.1:5000（缺协议）	Zotero 发起 HTTPS 混合内容拦截或 DNS 解析失败
路径后缀	http://127.0.0.1:5000（插件自动补全 /v1/chat/completions）	http://127.0.0.1:5000/v1/translate	404 Not Found（v2+ 已弃用该路径）

四、兼容层：DeeplX 版本与 OpenAI 兼容接口演进

DeeplX v1.x 使用自定义 REST 接口（/translate），而当前主流 Zotero 插件（如 zotero-deeplx v3.2+）强制依赖 OpenAI 兼容协议（/v1/chat/completions）。必须验证版本：

deeplx --version  # 应输出 ≥ v2.0.0
# 若为 v1.8.3，需升级：
npm install -g deeplx-api@latest  # Node.js 方式
# 或下载预编译二进制：https://github.com/OwO-Network/DeeplX/releases/tag/v2.1.0

五、权限层：Zotero 插件策略与字段粒度控制

• 进入 Zotero → 首选项 → 插件 → Deeplx → 设置；
• 确认勾选：✅ 启用自动翻译、✅ 翻译 PDF 元数据、✅ 翻译标题/作者/摘要/关键词；
• 注意：“仅当添加新条目时触发” 与 “实时监听字段修改” 是两个独立开关，须同时启用；
• 若使用 Zotero 7+，检查 about:config 中 extensions.zotero.deeplx.debug 设为 true 启用日志。

六、系统层：区域设置引发的编码隐性故障

中文 Windows 默认区域为“中文（简体，中国）”，其 ANSI 编码为 GBK。当 DeeplX 服务以 UTF-8 解析请求但系统环境变量 LANG=zh_CN.GBK 时，Node.js 进程可能错误解码 POST body，导致 JSON.parse() 抛出 SyntaxError: Unexpected token 。解决方案：

1. 启动 DeeplX 前显式指定编码：chcp 65001 && deeplx --port 5000（Windows）；
2. Linux/macOS 下，在 ~/.bashrc 添加：export LANG=en_US.UTF-8；
3. 或修改 DeeplX 启动脚本，强制设置 process.env.NODE_OPTIONS = '--icu-data-dir=./icu'。

七、可观测层：结构化日志驱动的根因定位

graph TD
    A[Zotero 控制台] -->|F12 打开 DevTools| B[Console 标签页]
    B --> C{筛选 'deeplx'}
    C --> D[404: URL 路径错误]
    C --> E[502: 服务未响应/反向代理中断]
    C --> F[timeout: 网络延迟＞10s]
    C --> G[SyntaxError: JSON 响应格式异常]
    D --> H[检查插件 URL 配置]
    E --> I[验证 deeplx 进程 + health 端点]
    F --> J[测试 curl -w '@curl-format.txt' -o /dev/null -s http://127.0.0.1:5000/health]

八、验证闭环：端到端冒烟测试清单

1. ✅ curl -X POST http://127.0.0.1:5000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"deelplx","messages":[{"role":"user","content":"hello"}]}' 返回 200 + JSON；
2. ✅ Zotero 插件设置中 URL 为 http://127.0.0.1:5000（无尾斜杠、无 https、无 /v1）；
3. ✅ Zotero 调试日志显示 [Deeplx] Sending translation request for field: abstract；
4. ✅ 文献条目右键出现 Translate selected field 子菜单；
5. ✅ 修改英文摘要后，Zotero 自动填充中文翻译（非手动触发）。

```