codex-bilingual-reader-for-zotero 0.0.0-stage → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +30 -0
- package/LICENSE +21 -0
- package/README.md +240 -2
- package/build/codex-bilingual-reader.xpi +0 -0
- package/build/codex-bilingual-runtime.zip +0 -0
- package/package.json +22 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.6.0 - 2026-11-19
|
|
4
|
+
|
|
5
|
+
- Translate with neighboring text from BabelDOC across page and column breaks. Batch requests retain paragraph IDs and checkpoints account for context and backend settings.
|
|
6
|
+
- Discover, provision and verify the managed runtime from Zotero settings. Show installation stages, keep paths under advanced settings, and refresh launcher scripts when the XPI changes.
|
|
7
|
+
- Resolve the Windows portable engine relative to its workspace and use the detected interpreter for PDF margin adjustments on macOS and Linux. An original attachment in a directory named “bilingual” can now be translated.
|
|
8
|
+
|
|
9
|
+
## 1.5.0 - 2026-10-21
|
|
10
|
+
|
|
11
|
+
- Add macOS/Linux support for the preserved-layout PDF workflow. One-click setup now runs `scripts/install-preserved-pdf-runtime.sh`, which provisions a Python 3.10-3.13 virtualenv (via `uv` when available) and installs the pinned `pdf2zh_next` 2.9.0 / `BabelDOC` 0.6.2 engine stack.
|
|
12
|
+
- Introduce `scripts/pdf-runtime-paths.mjs`, a shared module that resolves portable, virtualenv, and custom runtime layouts on every platform and normalises proxy/`HF_ENDPOINT` defaults.
|
|
13
|
+
- Keep the real `HOME` on macOS/Linux so BabelDOC reuses `~/.cache/babeldoc` instead of re-downloading its ~340 MB layout model and fonts on every run.
|
|
14
|
+
- Detect the engine, `pdftoppm`, `pdftotext`, and LibreOffice in their native macOS locations (`/opt/homebrew/bin`, `/Applications/LibreOffice.app`), and lower the default worker count on Apple Silicon.
|
|
15
|
+
- Reduce the default inner-margin trim to the actual blank gutter: dual PDFs are measured pixel by pixel so the compaction step can never clip the first character of a translated line.
|
|
16
|
+
- Make the path placeholders and installer copy platform neutral, add a macOS GitHub Actions job, and make `npm test` work on systems without a bare `python` executable.
|
|
17
|
+
|
|
18
|
+
## 1.4.6 - 2026-10-20
|
|
19
|
+
|
|
20
|
+
- Support Zotero 10: raise `strict_max_version` from `9.*` to `10.*` so the add-on installs and stays enabled on Zotero 10.0.x.
|
|
21
|
+
- Verified against Zotero 10.0.6 (Gecko 140): bootstrap startup, preference-pane registration and item-pane/custom-section hooks load without errors.
|
|
22
|
+
- Checked for API drift against the Zotero 10.0.6 source; `PreferencePanes`, `ItemPaneManager`, `Reader.open`, `Reader._readers`, `FullText`, `Attachments`, `ProgressWindow` and the `menu_ToolsPopup` / `zotero-itemmenu` anchors are unchanged.
|
|
23
|
+
|
|
24
|
+
## 1.3.71 - 2026-08-17
|
|
25
|
+
|
|
26
|
+
- Generate selectable preserved-layout English/Chinese PDFs and import them into Zotero.
|
|
27
|
+
- Translate with local Codex CLI or OpenAI-compatible APIs including OpenAI and DeepSeek.
|
|
28
|
+
- Batch selected papers with running and waiting task states, cancellation, checkpoints, and resumable translation.
|
|
29
|
+
- Track page/fragment progress, elapsed time, actual API token usage, and configurable cost.
|
|
30
|
+
- Add Zotero Tools, context-menu, and right-pane integrations with bilingual-PDF preview and center-gap adjustment.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Codex Bilingual Reader contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,241 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/fangchenghao/codex-bilingual-reader/main/addon/content/icons/icon.svg" width="112" alt="Codex Bilingual Reader logo">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">Codex Bilingual Reader for Zotero</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">由 Codex 或 OpenAI 兼容 API 驱动的保排版中英论文翻译插件<br>Preserved-layout English/Chinese paper translation powered by Codex or OpenAI-compatible APIs</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://github.com/fangchenghao/codex-bilingual-reader/releases/latest"><img src="https://img.shields.io/github/v/release/fangchenghao/codex-bilingual-reader" alt="Latest release"></a>
|
|
11
|
+
<a href="https://github.com/fangchenghao/codex-bilingual-reader/actions/workflows/ci.yml"><img src="https://github.com/fangchenghao/codex-bilingual-reader/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
12
|
+
<a href="https://github.com/fangchenghao/codex-bilingual-reader/blob/main/LICENSE"><img src="https://img.shields.io/github/license/fangchenghao/codex-bilingual-reader" alt="MIT license"></a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center"><a href="#中文">简体中文</a> · <a href="#english">English</a></p>
|
|
16
|
+
|
|
17
|
+

|
|
18
|
+
|
|
19
|
+
## 中文
|
|
20
|
+
|
|
21
|
+
Codex Bilingual Reader 是一个适用于 Zotero 8/9/10 的 MIT 开源插件。它可通过本地已登录的 Codex CLI,或 OpenAI、DeepSeek 等 OpenAI 兼容 API,将 PDF 附件转换为**保留原排版的中英对照 PDF**。生成结果会作为独立的 Zotero 子附件自动导入,原始 PDF 始终不会被修改。
|
|
22
|
+
|
|
23
|
+
> 本项目源自 [Mengqi97/codex-bilingual-reader-for-zotero](https://github.com/Mengqi97/codex-bilingual-reader-for-zotero)(MIT 许可)。上游已停止更新,当前由 [fangchenghao](https://github.com/fangchenghao) 维护,重点是维持对新版 Zotero 的兼容(本版适配 Zotero 10.0.x)。
|
|
24
|
+
|
|
25
|
+
### 核心功能
|
|
26
|
+
|
|
27
|
+
- **保排版中英对照 PDF**:保留图片、公式、表格、可选择文字和页面几何结构,并将英文与中文并列排版。
|
|
28
|
+
- **Codex 与多种 API 后端**:支持本地 Codex CLI、OpenAI、DeepSeek 及其他 OpenAI 兼容接口。
|
|
29
|
+
- **单篇与批量翻译**:支持翻译单篇论文或批量加入队列,并显示运行、等待、取消和断点续传状态。
|
|
30
|
+
- **原生 Zotero 操作入口**:可从工具菜单、条目右键菜单或右侧面板启动;完成后自动导入双语 PDF。
|
|
31
|
+
- **任务与费用统计**:集中查看页数/片段进度、运行时间、实际 API Token 用量、可配置价格及失败信息。
|
|
32
|
+
- **双语 PDF 设置**:可选择译文位于左侧或右侧、默认打开原文或双语附件、预览输出,并可单独调整中缝宽度而无需重新翻译。
|
|
33
|
+
|
|
34
|
+
### 效果展示
|
|
35
|
+
|
|
36
|
+

|
|
37
|
+
|
|
38
|
+
上图中英文位于左侧,可选择的中文译文位于右侧;图片、公式、表格和页面结构均得到保留。
|
|
39
|
+
|
|
40
|
+
### 安装
|
|
41
|
+
|
|
42
|
+
1. 从[最新 GitHub Release](https://github.com/fangchenghao/codex-bilingual-reader/releases/latest)下载 `codex-bilingual-reader.xpi`。
|
|
43
|
+
2. 在 Zotero 中打开**工具 → 扩展和主题**(Zotero 9 及更早版本叫**附加组件**),点击右上角齿轮,选择**从文件安装附加组件…**,然后选择下载的 XPI。
|
|
44
|
+
3. 打开**工具 → Codex 中英对照设置…**,点击**一键安装/修复 PDF 翻译环境**。Windows 会下载并解压约 600 MB 的官方便携引擎;macOS/Linux 会在插件运行目录中创建 Python 虚拟环境并安装 `pdf2zh_next` / `BabelDOC`(约 900 MB)。两种方式通常都需要几分钟。
|
|
45
|
+
4. 选择本地 Codex CLI 或 OpenAI 兼容 API,配置模型和凭据,并在翻译前点击**测试连接**。
|
|
46
|
+
|
|
47
|
+
也可以用 `npm pack codex-bilingual-reader-for-zotero` 下载发布包。解压生成的 `.tgz`,在第 2 步选择其中的 `package/build/codex-bilingual-reader.xpi`。
|
|
48
|
+
|
|
49
|
+
### 保排版 PDF 配置
|
|
50
|
+
|
|
51
|
+
打开设置后可以看到 PDF 环境是否就绪。点击安装按钮会显示下载、安装和校验阶段。预检成功后插件才保存路径。已有环境可以展开**高级设置 · 查看或更改路径**,选择工作目录或手动填写。升级插件后,托管目录中的启动脚本会自动更新,已有引擎可以继续使用。
|
|
52
|
+
|
|
53
|
+
平台支持:
|
|
54
|
+
|
|
55
|
+
- **Windows**:一键安装下载官方便携包并执行 SHA-256 校验;若系统没有 Node.js,会一并安装官方便携版本。
|
|
56
|
+
- **macOS / Linux**:一键安装在 `codex-bilingual-runtime/.venv` 中创建虚拟环境,优先复用 Node.js 20+、Python 3.10–3.13 和已有的 `uv`。在支持的 x64 / arm64 macOS 和 glibc Linux 上,缺少工具时会校验并下载 Node.js 或 uv 到插件运行目录,再按需准备 Python 3.12。首次运行 BabelDOC 还会从镜像下载约 340 MB 的版面模型与字体到 `~/.cache/babeldoc`。
|
|
57
|
+
|
|
58
|
+
PDFMathTranslate-next/BabelDOC 使用 AGPL 许可证,因此它由用户主动下载并作为独立外部引擎运行,MIT 插件不会捆绑或链接其代码。关于调用协议、隐私边界、许可证边界和验收标准,请参阅[保排版 PDF 工作流](https://github.com/fangchenghao/codex-bilingual-reader/blob/main/docs/PDF_PRESERVATION_WORKFLOW.md)。
|
|
59
|
+
|
|
60
|
+
### 使用入口与设置
|
|
61
|
+
|
|
62
|
+
选中论文后,可从以下任一入口启动翻译:
|
|
63
|
+
|
|
64
|
+
- **工具 → 使用 Codex 生成全文中英对照**
|
|
65
|
+
- 论文条目的右键菜单
|
|
66
|
+
- Zotero 右侧条目面板中的 **Codex 中英对照** 区域
|
|
67
|
+
|
|
68
|
+
可通过**编辑 → 设置 → Codex 中英对照**、**工具 → Codex 中英对照设置…**,或右侧面板的**翻译设置**按钮打开配置页面。
|
|
69
|
+
|
|
70
|
+
- **保排版 PDF(默认)**:Codex CLI 使用本地登录和所选推理强度;API 模式支持 OpenAI、DeepSeek 等 Chat Completions 兼容服务。
|
|
71
|
+
- **默认打开附件**:可选择双击论文时优先打开双语 PDF,或保持 Zotero 默认打开原始 PDF 的行为。
|
|
72
|
+
- **测试连接**:验证保排版启动器,并通过所选后端翻译一个最小测试句,不会发送论文正文。
|
|
73
|
+
|
|
74
|
+
### 跨页句子的翻译
|
|
75
|
+
|
|
76
|
+
保排版模式使用 BabelDOC 识别的正文阅读顺序。对于引擎配对的跨页或跨栏段落,模型会看到前后片段的原文摘录,每个片段的译文按段落编号放回原位。分批、断点续传和单段重试都使用相同的上下文。升级后首次重译会重新请求旧版缓存中的片段。复杂版面中误识别的页眉、脚注或正文仍可能影响衔接。
|
|
77
|
+
|
|
78
|
+
### 典型处理时间
|
|
79
|
+
|
|
80
|
+
翻译速度取决于 PDF 排版复杂度、网络延迟、模型服务和并发限制。在 1.5.x 的 DeepSeek API 测试中,普通 8 页学术 PDF 约需 10 分钟。公式、表格、双栏排版较多或服务繁忙时可能更久;该数值是经验参考,不是性能保证。
|
|
81
|
+
|
|
82
|
+
### 安全与隐私
|
|
83
|
+
|
|
84
|
+
使用 Codex CLI 时,文本片段通过用户本地的 Codex 登录提交,插件不会读取或复制 Codex 凭据。使用 API 模式时,API Key 保存在本地 Zotero 首选项中,仅作为 Bearer 凭据发送到用户配置的 Base URL。无论使用哪种方式,论文文本都会发送给所选翻译服务商。
|
|
85
|
+
|
|
86
|
+
在 Windows 上,启动器通过标准输入将文档片段传给配置的 `codex.cmd` 或 `codex.exe`,不会把 PDF 文本拼接到 Shell 命令中。
|
|
87
|
+
|
|
88
|
+
### 已知限制
|
|
89
|
+
|
|
90
|
+
- 扫描型 PDF 不会由本插件执行 OCR,请先在 Zotero 或其他工具中完成 OCR。
|
|
91
|
+
- 保排版 PDF 需要单独安装 PDFMathTranslate-next,并具备可用的 Codex CLI 登录或 OpenAI 兼容 API 配置。
|
|
92
|
+
- PDF 引擎需要 Python 3.10–3.13,由安装器负责查找或准备。未设置 `HF_ENDPOINT` 时会默认使用 `https://hf-mirror.com` 下载 BabelDOC 模型,若你的网络无法访问该镜像,请自行设置 `HF_ENDPOINT`。
|
|
93
|
+
- 只有 API 服务返回标准 `usage` 对象时才能显示精确 Token 用量;Codex CLI 当前不提供权威 Token 统计。
|
|
94
|
+
- Zotero 全文缓存没有稳定的“段落到 PDF 坐标”映射,因此当前版本无法从双语内容精确跳转回 PDF 中的对应位置。
|
|
95
|
+
- Codex App Server 依赖有效的 `~/.codex/config.toml`;若出现 TOML 解析错误,需要先修复提示的配置行。
|
|
96
|
+
|
|
97
|
+
### 开发
|
|
98
|
+
|
|
99
|
+
环境要求:Node.js 20+、Python 3.10+(`npm test` 中的 Python 用例需要)、Zotero 8+。以下命令在 Windows(Git Bash / PowerShell 均可)、macOS 和 Linux 上一致。
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npm ci # 安装固定依赖
|
|
103
|
+
npm run check # 语法与清单校验
|
|
104
|
+
npm test # Node 测试 + Python 批量翻译器测试
|
|
105
|
+
npm run build # 产出分发包
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
构建产物位于 `build/codex-bilingual-reader.xpi`。
|
|
109
|
+
|
|
110
|
+
只验证保排版启动器、不翻译正文:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
node scripts/translate-preserved-pdf-cli.mjs --check
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
若本机还没有 PDF 引擎,可先准备运行时再重跑上面的预检:macOS/Linux 用 `bash scripts/install-preserved-pdf-runtime.sh --runtime-root "$PWD/.runtime/pdf2zh"`,Windows 用 `scripts/install-preserved-pdf-runtime.ps1`。
|
|
117
|
+
|
|
118
|
+
### 致谢与参考项目
|
|
119
|
+
|
|
120
|
+
本项目在插件架构、交互设计、PDF 保排版流程和兼容接口方面参考或使用了以下优秀开源项目:
|
|
121
|
+
|
|
122
|
+
- [PDFMathTranslate-next](https://github.com/PDFMathTranslate-next/PDFMathTranslate-next)
|
|
123
|
+
- [BabelDOC](https://github.com/funstory-ai/BabelDOC)
|
|
124
|
+
- [llm-for-zotero](https://github.com/yilewang/llm-for-zotero)
|
|
125
|
+
- [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template)
|
|
126
|
+
- [Translate for Zotero / zotero-pdf-translate](https://github.com/windingwind/zotero-pdf-translate)
|
|
127
|
+
|
|
128
|
+
感谢这些项目及其贡献者。PDFMathTranslate-next/BabelDOC 作为独立外部 AGPL 引擎运行;所有相关项目仍分别遵循各自的许可证。
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## English
|
|
133
|
+
|
|
134
|
+
Codex Bilingual Reader is an MIT-licensed plugin for Zotero 8/9/10. It converts PDF attachments into **preserved-layout English/Chinese PDFs** using either the locally authenticated Codex CLI or an OpenAI-compatible API such as OpenAI or DeepSeek. The generated PDF is imported automatically as a separate Zotero child attachment, and the original PDF is never modified.
|
|
135
|
+
|
|
136
|
+
> Derived from [Mengqi97/codex-bilingual-reader-for-zotero](https://github.com/Mengqi97/codex-bilingual-reader-for-zotero) (MIT). The upstream project is no longer maintained; this fork is maintained by [fangchenghao](https://github.com/fangchenghao) with a focus on staying compatible with newer Zotero releases (this version targets Zotero 10.0.x).
|
|
137
|
+
|
|
138
|
+
### Core features
|
|
139
|
+
|
|
140
|
+
- **Preserved-layout bilingual PDF** — retains figures, formulas, tables, selectable text, and page geometry while placing English and Chinese side by side.
|
|
141
|
+
- **Codex and multiple API backends** — supports the local Codex CLI, OpenAI, DeepSeek, and other OpenAI-compatible endpoints.
|
|
142
|
+
- **Single and batch translation** — translates one paper or queues multiple selected papers with running, waiting, cancellation, and resumable checkpoint states.
|
|
143
|
+
- **Native Zotero entry points** — starts from the Tools menu, item context menu, or right-hand pane and automatically imports completed PDFs.
|
|
144
|
+
- **Task and cost tracking** — displays page/fragment progress, elapsed time, actual API token usage, configurable pricing, and failures in one task center.
|
|
145
|
+
- **Bilingual PDF controls** — selects the translation side, preferred attachment on open, output preview, and center-gap adjustment without retranslating.
|
|
146
|
+
|
|
147
|
+
### Preview
|
|
148
|
+
|
|
149
|
+

|
|
150
|
+
|
|
151
|
+
English is preserved on the left and the translated, selectable Chinese page is placed on the right while figures, formulas, tables, and page geometry remain intact.
|
|
152
|
+
|
|
153
|
+
### Installation
|
|
154
|
+
|
|
155
|
+
1. Download `codex-bilingual-reader.xpi` from the [latest GitHub Release](https://github.com/fangchenghao/codex-bilingual-reader/releases/latest).
|
|
156
|
+
2. In Zotero, open **Tools → Add-ons and Themes** (named **Add-ons** in Zotero 9 and earlier), click the gear icon, choose **Install Add-on From File…**, and select the downloaded XPI.
|
|
157
|
+
3. Open **Tools → Codex 中英对照设置…** and click **一键安装/修复 PDF 翻译环境**. On Windows this downloads and extracts the official portable engine (about 600 MB); on macOS/Linux it creates a Python virtual environment in the add-on runtime directory and installs `pdf2zh_next` / `BabelDOC` (about 900 MB). Either path normally takes a few minutes.
|
|
158
|
+
4. Select the locally authenticated Codex CLI or an OpenAI-compatible API, configure the model and credentials, and run **Test connection** before translating a paper.
|
|
159
|
+
|
|
160
|
+
To download the release through npm, run `npm pack codex-bilingual-reader-for-zotero`. Extract the resulting `.tgz` and select `package/build/codex-bilingual-reader.xpi` in step 2.
|
|
161
|
+
|
|
162
|
+
### Preserved-layout PDF setup
|
|
163
|
+
|
|
164
|
+
Settings checks the local runtime and shows each installation stage. Paths are saved after preflight succeeds. Expand **高级设置 · 查看或更改路径** to select an existing workspace or edit paths. Updating the XPI refreshes the managed launcher scripts on the next use.
|
|
165
|
+
|
|
166
|
+
Platform support:
|
|
167
|
+
|
|
168
|
+
- **Windows**: one-click setup downloads the official portable bundle and verifies it with SHA-256; a portable Node.js is installed as well when none is present.
|
|
169
|
+
- **macOS / Linux**: one-click setup creates a virtual environment at `codex-bilingual-runtime/.venv` and reuses available Node.js 20+, Python 3.10–3.13, and uv installations. On x64 / arm64 macOS and glibc Linux, the installer can download checksum-verified Node.js and uv into the runtime and provision Python 3.12 as needed. The first run also downloads about 340 MB of BabelDOC layout models and fonts into `~/.cache/babeldoc`.
|
|
170
|
+
|
|
171
|
+
PDFMathTranslate-next/BabelDOC is downloaded on explicit user action and runs as a separate external AGPL engine; it is not bundled or linked into the MIT plugin. See [the preserved PDF workflow](https://github.com/fangchenghao/codex-bilingual-reader/blob/main/docs/PDF_PRESERVATION_WORKFLOW.md) for provider contracts, privacy boundaries, license boundaries, and acceptance gates.
|
|
172
|
+
|
|
173
|
+
### Entry points and settings
|
|
174
|
+
|
|
175
|
+
With a paper selected, start translation from any of these entries:
|
|
176
|
+
|
|
177
|
+
- **Tools → 使用 Codex 生成全文中英对照**
|
|
178
|
+
- The paper item's context menu
|
|
179
|
+
- The **Codex 中英对照** section in Zotero's right-hand item pane
|
|
180
|
+
|
|
181
|
+
Open settings through **Edit → Settings → Codex 中英对照**, **Tools → Codex 中英对照设置…**, or the **翻译设置** button in the right-hand pane.
|
|
182
|
+
|
|
183
|
+
- **Preserved PDF (default)** — Codex CLI uses the local login and selected reasoning level; API mode supports OpenAI, DeepSeek, and other Chat Completions-compatible providers.
|
|
184
|
+
- **Default open attachment** — chooses whether double-clicking a paper prefers its bilingual PDF or retains Zotero's original-PDF behavior.
|
|
185
|
+
- **Test connection** — validates the preserved-PDF launcher and translates one minimal test sentence through the selected backend without sending a document.
|
|
186
|
+
|
|
187
|
+
### Sentences spanning pages
|
|
188
|
+
|
|
189
|
+
When BabelDOC identifies adjacent body paragraphs across a page or column break, each translation receives short excerpts from its neighbors. The broker preserves that context across batches and retries and maps each translation to its original paragraph ID. The first translation after upgrading requests fresh translations for fragments cached by older versions. Reading order depends on the layout engine correctly identifying body text.
|
|
190
|
+
|
|
191
|
+
### Typical processing time
|
|
192
|
+
|
|
193
|
+
Translation time depends on PDF layout complexity, network latency, model availability, and provider rate limits. In a 1.5.x test, an eight-page academic PDF took about ten minutes with the DeepSeek API. Formula-heavy, table-heavy, multi-column documents or provider congestion may take longer; this is an observed estimate, not a performance guarantee.
|
|
194
|
+
|
|
195
|
+
### Security and privacy
|
|
196
|
+
|
|
197
|
+
With Codex CLI, source fragments are submitted through the user's local Codex login, and the plugin never reads or copies Codex credentials. With API mode, the API key remains in the local Zotero preference profile and is sent only as a Bearer credential to the configured Base URL. In either mode, document text is sent to the selected translation provider.
|
|
198
|
+
|
|
199
|
+
On Windows, the launcher sends document fragments through stdin to the configured `codex.cmd` or `codex.exe`; it never interpolates PDF text into a shell command.
|
|
200
|
+
|
|
201
|
+
### Known limitations
|
|
202
|
+
|
|
203
|
+
- Scanned PDFs are not OCRed by this plugin. Run OCR in Zotero or another tool first.
|
|
204
|
+
- Preserved PDF output requires a separately installed PDFMathTranslate-next engine and either a valid Codex CLI login or a working OpenAI-compatible API configuration.
|
|
205
|
+
- The runtime needs Python 3.10–3.13. Setup finds or provisions a compatible interpreter. When `HF_ENDPOINT` is unset the launcher defaults to `https://hf-mirror.com` for BabelDOC model downloads; override it if that mirror is unreachable from your network.
|
|
206
|
+
- Exact token usage is displayed only when an API provider returns a standard `usage` object. Codex CLI tasks do not currently expose authoritative token counts.
|
|
207
|
+
- Zotero's full-text cache does not retain a robust paragraph-to-PDF coordinate map, so the current version cannot jump from bilingual content to the exact corresponding PDF location.
|
|
208
|
+
- The Codex App Server requires a valid `~/.codex/config.toml`. Fix the reported configuration line before retrying if a TOML parse error occurs.
|
|
209
|
+
|
|
210
|
+
### Development
|
|
211
|
+
|
|
212
|
+
Requirements: Node.js 20+, Python 3.10+ (needed by the Python cases in `npm test`), and Zotero 8+. The commands below are identical on Windows (Git Bash or PowerShell), macOS, and Linux.
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
npm ci # install pinned dependencies
|
|
216
|
+
npm run check # syntax and manifest checks
|
|
217
|
+
npm test # Node tests + Python batch-translator tests
|
|
218
|
+
npm run build # produce the distributable
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
The distributable is `build/codex-bilingual-reader.xpi`.
|
|
222
|
+
|
|
223
|
+
To validate the preserved-layout launcher without translating any content:
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
node scripts/translate-preserved-pdf-cli.mjs --check
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
If the machine has no PDF engine yet, provision the runtime first and rerun the preflight: `bash scripts/install-preserved-pdf-runtime.sh --runtime-root "$PWD/.runtime/pdf2zh"` on macOS/Linux, or `scripts/install-preserved-pdf-runtime.ps1` on Windows.
|
|
230
|
+
|
|
231
|
+
### Acknowledgements and references
|
|
232
|
+
|
|
233
|
+
This project references or builds on the ideas, plugin interactions, preserved-layout workflow, and compatible interfaces of these excellent open-source projects:
|
|
234
|
+
|
|
235
|
+
- [PDFMathTranslate-next](https://github.com/PDFMathTranslate-next/PDFMathTranslate-next)
|
|
236
|
+
- [BabelDOC](https://github.com/funstory-ai/BabelDOC)
|
|
237
|
+
- [llm-for-zotero](https://github.com/yilewang/llm-for-zotero)
|
|
238
|
+
- [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template)
|
|
239
|
+
- [Translate for Zotero / zotero-pdf-translate](https://github.com/windingwind/zotero-pdf-translate)
|
|
240
|
+
|
|
241
|
+
Many thanks to their maintainers and contributors. PDFMathTranslate-next/BabelDOC remains a separately installed external AGPL engine, and every referenced project continues to be governed by its own license.
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,24 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codex-bilingual-reader-for-zotero",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.6.0",
|
|
4
|
+
"description": "Create preserved-layout English-Chinese PDFs in Zotero with Codex CLI or OpenAI-compatible APIs.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/fangchenghao/codex-bilingual-reader.git"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"build/codex-bilingual-reader.xpi",
|
|
12
|
+
"build/codex-bilingual-runtime.zip",
|
|
13
|
+
"CHANGELOG.md"
|
|
14
|
+
],
|
|
15
|
+
"scripts": {
|
|
16
|
+
"build": "node scripts/build.mjs",
|
|
17
|
+
"prepack": "npm run build",
|
|
18
|
+
"check": "node scripts/check.mjs",
|
|
19
|
+
"test": "node --test tests/*.test.mjs && (command -v python3 >/dev/null && python3 -m unittest tests/test_batch_broker.py || python -m unittest tests/test_batch_broker.py)"
|
|
20
|
+
},
|
|
21
|
+
"engines": {
|
|
22
|
+
"node": ">=20"
|
|
23
|
+
}
|
|
24
|
+
}
|