Doc2X Zotero Plugin: Illustrated Guide

Select paper PDFs in Zotero, translate them, and save the results under their original parent items. This guide follows the current 1.1.12 interface and covers Combine translation and sequential PDF batches. Screenshots show the Chinese interface; translated instructions are provided below each illustration.

Workflow

Install the matching plugin → sign in to the desktop client → configure translation → select PDFs → open notes and PDFs. Start with one short paper before processing a batch.

1. Download and install

Choose the correct package

Open the official download page and find the Zotero plugin card.

Zotero version	Download option
Zotero 9 or 10	9 / 10
Zotero 7 or 8	7 / 8
Zotero 6	Unsupported; upgrade Zotero first

Keep the downloaded .xpi file intact. In Zotero, open Tools → Plugins, use the gear menu and Install Plugin From File, select the .xpi, and restart if prompted. Dragging the file into the plugin manager is another option.

Better Notes is no longer required. You may keep it if already installed. Use Windows 10/11; the Doc2X macOS desktop client currently targets Apple silicon.

Update an existing installation

Check for updates in Zotero's plugin manager, or install the matching .xpi from the website. If menus are missing or the plugin behaves incorrectly afterward, uninstall the old plugin, fully quit Zotero, reopen it, and install the correct package.

When moving from Zotero 7/8 to 9/10, switch to the 9/10 package. This plugin update does not require a simultaneous Doc2X desktop client update if your existing client works and is signed in.

2. Connect and configure

1. Open the Doc2X desktop client, sign in, and keep it running on the same computer as Zotero.
2. Open Zotero Settings → Doc2X. Settings is under Edit on Windows and Zotero on macOS.
3. Click Get Token and verify the authorization status and available quota. Never share the Token in public screenshots.
4. Select a model, target language, glossary, and output formats. Available models, membership requirements, and charges are shown in the current interface.
5. Check I have completed the parsing and translation configuration before starting.

Output settings determine which notes and PDFs are saved. Enable the bilingual and layout-preserving outputs you need.

3. Translate one paper with Combine

The Chinese menu entry is PDF => 双语对照+排版翻译（Pro专属）, meaning bilingual plus layout-preserving translation, Pro only. One task produces both types of reading results. Confirm that your account has the required Pro entitlement.

1. Expand a paper's parent item and select its original PDF attachment.
2. Right-click the PDF and open the Doc2X translation options submenu.
3. Choose bilingual plus layout-preserving translation. If selecting from a parent with multiple PDFs, choose the intended attachment first.
4. Wait for upload, parsing, translation, and saving to finish.

Operation diagram based on the actual menu. Placement can vary between Zotero versions.

What are the two result types?

• Bilingual notes: original and translated text for comparison. Text is translated rather than merely retained as the original. Original-only and translated-only notes can also be saved according to settings.
• Layout-preserving PDFs: a translated PDF preserving the original layout, with an optional side-by-side bilingual PDF according to your output settings.

“Two results” means two categories, not exactly two files. With relevant outputs enabled, a paper may produce three notes and two PDFs. Ignore options, recognition quality, and model behavior affect the contents; not every element is guaranteed to be translated.

Use the individual bilingual or layout-preserving menu if you need only one category. Use parsing when translation is unnecessary.

4. Translate multiple papers sequentially

1. Expand paper items and select their original PDFs. Hold Ctrl on Windows or Command on macOS to select multiple attachments; Shift selects a range. Avoid selecting previously generated translated PDFs.
2. Right-click and choose 批量双语对照+排版翻译 (batch bilingual plus layout-preserving translation). Individual bilingual and layout-preserving batch modes are also available.
3. If selecting parent items, use 选择本次批量翻译的 PDF (choose PDFs for this batch), tick the intended files, and confirm the selection.
4. Review the PDF count, filenames, and quota notice before confirming.
5. Wait while the plugin completes one PDF before starting the next. Each paper's results return to its own parent item.

Each PDF creates a new task and consumes the applicable quota. The batch stops after the first failure. Choosing “stop batch translation after the current file” lets the current file finish and prevents subsequent files from starting.

5. Find your results

Expand the original paper's parent item:

• Open the bilingual, translated, or original MD notes to read their contents.
• Double-click the layout-preserving translated or bilingual PDF to open it in Zotero's reader.
• Supported result notes offer Doc2X: Preview Markdown and Doc2X: View on web. Combined tasks open the reading format associated with the selected result.

Filenames can include output type, language, and model. A batch does not put every result under the first paper.

Costs, failures, and repeat submissions

Parsing uses parsing pages; translation follows your model and account entitlements. Check the interface for current rules. Combine translation is not free translation, and batching does not waive per-file charges.

• Do not repeatedly click start while waiting. Starting the same PDF again in Zotero creates a new task and may consume pages and credits again.
• If parsing succeeded but translation failed, find the task in the Doc2X client and use the available Continue translation action, then export to Zotero. This avoids unnecessary repeat parsing.
• After a batch failure, identify completed files, resolve the failure, and select only unfinished files when resuming.
• Large documents and slower models can take time. Unchanged progress does not necessarily mean failure; inspect the task in the client. Start with a short PDF.

Frequently asked questions

The Combine or batch menu is missing

Check that you installed the latest package matching your Zotero version. Combine is Pro only. Batch menus require multiple eligible PDFs or parent items; notes, empty items, and single selections show different menus. Complete translation configuration first.

How do I choose between multiple PDFs under one item?

Right-click the intended attachment directly or explicitly choose it from the parent item's attachment selector. Review filenames again in the batch confirmation.

Get Token fails or the desktop client disconnects

Verify that the Doc2X client is running and signed in on the same computer. Restart both applications if needed, then obtain authorization again. An Open Platform API key is not the desktop Token used here.

Only one category of results appears

Check output settings, expand the parent item, and confirm the task has finished saving. Combine and standalone bilingual translation are different menu actions. Inspect the task before submitting it again.

Do I still need Better Notes as shown in the video?

No. Some steps in the older video are outdated. Follow this guide for current installation and menu instructions.

Feedback

Contact us with your Zotero version, plugin version, failure stage, and redacted screenshots. Do not share Tokens or sensitive account information.