Zotero PDF2zh: run PDFMathTranslate inside Zotero, with a local server in the loop

What Zotero PDF2zh actually solves for a Zotero user

Zotero stores and cites PDFs. It does not translate them. PDFMathTranslate (PDF2zh) and its successor PDF2zh_next do translate PDFs while trying to preserve formulas and layout, but they are command-line tools with their own configuration surface. Zotero PDF2zh is the bridge: a Zotero plugin that hands a PDF to a locally running PDF2zh or PDF2zh_next process and attaches the translated result back to the Zotero item.

The audience is narrow and specific. You need Zotero 7, 8, 9 or 10 (the README badges list all four), a machine where you can install Python, and a willingness to keep a server process running while you work. In exchange you get dual-language comparison, crop reading, batch translation and configuration of several LLM services from inside the Zotero settings pane, rather than from a shell.

The plugin is not a translation engine. It is a controller. Every quality question about the output (how a formula is rendered, how a table survives, how a term is translated) belongs to PDF2zh or PDF2zh_next, and every environment question belongs to the Python side. That split explains most of the support traffic the README anticipates, from network errors to environment mismatches.

The plugin plus local server architecture, and why it is two moving parts

The repository is laid out as two deliverables that ship separately. The plugin directory holds the Zotero extension, distributed as zotero-pdf-2-zh.xpi. The server directory holds the Python side, distributed as server.zip, with a docker and docker2 directory for containerized deployment. The README's download line points at three separate artifacts: the XPI, the Server zip, and the documentation site at zotero-pdf2zh.github.io.

That separation is the design, not an accident of packaging. The plugin runs inside Zotero's JavaScript environment and cannot host a Python translation pipeline. The server runs the PDF2zh stack and exposes it over HTTP or a socket. The v4.1.7 release notes describe remote and Docker translation attaching the result via HTTP, and state that old and new plugin protocols are compatible.

Recent releases read as a log of the transport being hardened rather than the translation being changed. v4.1.6 moved translation to a background task to avoid Windows long-connection Network Error, and stopped progress polling from interrupting the terminal progress bar. v4.1.5 fixed a mid-translation Network Error on Windows. v4.1.4 made attachment prefer the local machine and drew the terminal progress bar to the window width. If you are on Windows, the version you install matters more than the feature list suggests.

Installing Zotero PDF2zh: Python, uv, server, then the XPI

The README lays out seven numbered steps. Step zero is Python (3.12 recommended) and Zotero. Step one is an environment manager, with uv recommended if you have no preference. The README gives the uv install commands for macOS/Linux and Windows.

# macOS/Linux
wget -qO- https://astral.sh/uv/install.sh | sh
# Windows (run in PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After that, run uv --version. A version number means the install worked. If the command is not found, the README says to add the uv path to your environment variables and restart the terminal, and gives the export for macOS/Linux and the PowerShell equivalent.

Step two downloads the project files. The README warns Windows users not to create the project folder on the C: system drive, and shows switching to D: first. Step three starts the service. Step four downloads and installs the plugin. Step five is the Zotero-side plugin settings, step six covers translation options, and step seven covers package updates.

The update path is the part most people will need later. The README states that if you previously chose N at the update prompt, or the update failed, you can maintain the environment yourself:

cd server
python update_packages.py

That script reuses an existing uv or conda environment, and prefers uv when no environment exists. The README also states that users on pdf2zh_next below 2.9.0 are asked on first launch whether to update, and that environments at or above 2.9.0 skip the prompt. DeepSeek V4 defaults to no thinking, so an older environment can keep translating; the README says 2.9.0 is only needed if you manually turn thinking on.

Where Zotero PDF2zh breaks, and when it is the wrong tool

The failure modes in the release notes are transport failures, not translation failures. Windows Network Error appears in v4.1.5 and v4.1.6 as something being fixed, which tells you it recurred often enough to need two releases. Long-running connections between the plugin and the server are the weak joint, and the fix was to move translation into a background task rather than to make the connection more reliable.

Environment mismatch is the second failure mode. The plugin and the Server version separately, and the v4.1.7 notes ask you to update both. A mismatched pair is the first thing to check when something stops working after an upgrade. The v4.1.1 notes list fixes for Windows Conda paths, environment misdetection, and console log crashes, which is a fair summary of where a Python-backed Zotero plugin tends to hurt.

The wrong-tool case is straightforward. If you cannot open a terminal on the machine that holds your Zotero library, this is not for you. If you want translation as a service with no local process, the server architecture is a cost you will keep paying. And if you want to contribute code right now, the README states plainly that a full refactor is in progress, a new version is expected in September, and developers are asked not to submit contributions because they cannot be merged with the new version. That notice is dated 2026-08-19 in the README. For a project whose last push was on 2026-08-27, this is a codebase in transition, and the contribution freeze is the clearest signal of it.

Zotero PDF2zh against the Translate for Zotero approach

The obvious comparison is a Zotero translation plugin that calls a translation API directly and returns text, rather than re-rendering the PDF. Translate for Zotero-style plugins translate selections, abstracts or notes, and the output is text you read in place. Zotero PDF2zh instead produces a translated PDF file and attaches it to the item, which is why it depends on PDFMathTranslate and why formulas and layout are part of the promise.

The trade-off is real in both directions. Text translation is fast, needs no local Python, and is useless if the thing you cannot read is a page of equations and two-column layout. PDF re-rendering handles the page but inherits the full cost of the PDF2zh stack: an environment, a server process, and the transport failures described above. Zotero PDF2zh also offers dual-language comparison and crop reading, which only make sense because there is a rendered page to compare against.

If your reading is mostly prose, the heavier path buys you little. If your reading is mostly scanned or formula-dense papers, the lighter path cannot help you at all, and the OCR and scanned-document questions in the project's own FAQ are a sign of how often that case comes up.

Licence, maintenance and the cost of upgrading

The project is AGPL-3.0. For individual researchers installing the plugin and running the server locally, that is the ordinary case. If you plan to expose the server to other people, wrap it in a hosted service, or ship it inside something you distribute, AGPL-3.0 carries network-copyleft obligations that differ from permissive licences, and you should read the LICENSE file in the repository rather than take a summary. This is not legal advice.

On maintenance, the facts are these: the repository is not archived, and the last push was on 2026-08-27. Releases are frequent, with v4.1.5, v4.1.6 and v4.1.7 all landing between 2026-08-20 and 2026-08-23. Alongside that, the README carries a notice dated 2026-08-19 stating that a full refactor is underway, that a new version is expected in September, that current-version questions will not be answered promptly in the group, and that contributions are not being accepted because they cannot be merged with the new version.

Upgrade cost is therefore not zero. You upgrade two artifacts, and the release notes repeatedly ask you to keep them in step. The server side has its own update script, and the environment may prompt you about pdf2zh_next versions. Budget for an upgrade being a small maintenance task rather than a click.

Editorial conclusion

Adopt Zotero PDF2zh if you already read English-language PDFs inside Zotero, are comfortable installing Python 3.12 and uv or conda, and accept running a local server that the plugin talks to. Do not adopt it if you want a one-click store plugin, if you cannot run a terminal on the machine holding your library, or if you need a maintained, contribution-welcome codebase today: the README states a full refactor is underway and asks developers not to submit contributions because they cannot be merged with the new version. Before relying on it, verify three things on your own machine: that uv --version or conda --version resolves in the same shell you will start the server from, that your pdf2zh_next version is at least 2.9.0 if you intend to enable thinking mode, and that the plugin and Server versions you install match, since the v4.1.7 notes explicitly ask you to update both.

Frequently asked questions

Official sources

1. guaguastandup/zotero-pdf2zh on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases