Doc2X Zotero Plugin User Guide
This document provides instructions on how to install and use the Doc2X Zotero plugin for intelligent parsing and translation of PDF documents.
Prerequisites
1. Install Doc2X Client and Plugin
You need to download the following two components:
- Doc2X Official Client Download Link
- Doc2X Plugin XPI File Download Link
Note: Some browsers don't recognize XPI files and may report them as corrupted. We recommend using Edge or Chrome browsers to resolve this issue.
2. Register Doc2X Account
Registration Link: doc2x.noedgeai.com
Video Tutorial
Detailed Operation Video: https://www.bilibili.com/video/BV19Yf5YXEDF
Note: The video tutorial was recorded with an earlier version of the plugin, which included a step to install the "Better Notes for Zotero" plugin. The latest version (v1.0.31 and above) no longer depends on Better Notes for Zotero — you do not need to install it. Please follow this document for up-to-date instructions.
Usage Workflow
Step 1: Install Required Components
Ensure all the following components are installed:
- ✅ Zotero 7 / 8
- ✅ Doc2X Client
- ✅ Doc2X Plugin
Note: The latest version of the plugin has removed the dependency on Better Notes for Zotero. All features work without it.
Step 2: Configure Plugin Settings
After installation, open the plugin and desktop client (ensure you're logged into your Doc2X account).
Windows System Settings
- Supported Versions: Only Win10 and Win11 supported
- Not Supported: Zotero 6
- Access Path: Zotero → Edit → Settings
Mac System Settings
- Supported Versions: Currently only M-series chips supported
- Access Path: Zotero → Settings
Zotero Version Support
- The plugin supports Zotero 7 / 8
Important Reminder: If you need to update the Zotero plugin, you must first uninstall the old version → close Zotero → reopen Zotero → install the new version, otherwise various issues may occur due to Zotero bugs.
Step 3: Get Token
- Open the Doc2X client
- Click "Get Token" in the Zotero plugin settings
- Mac: Top-left status bar Zotero → Settings → Doc2X → Click Get Token
- Windows: Zotero → Edit → Settings → Doc2X → Click Get Token
- The plugin automatically retrieves authorization from the locally running Doc2X client
- Check token status and parsing quota display
Cost Information
- Paid Models: Consume points and parsing pages
- Free Models: Only consume parsing pages
Step 4: Configure Parsing and Translation Options
In the plugin settings page, you can configure the following options:
Parse Model
- doc2x-v2-2410 — Legacy model
- doc2x-v3-2509-beta — Latest model (recommended)
Translation Model
The plugin supports multiple translation models, including free and paid options:
- Free Models: Doubao-1.5-lite, gpt-4.1-nano, qwen-turbo-latest, etc.
- Paid Models (consume premium points): Doubao-1.5-pro, DeepSeek-V3, gpt-4.1-mini, qwen-max-latest, Kimi-K2, etc.
The available model list is dynamically loaded from the server. Refer to the plugin settings for the most current options.
Target Language
10 target languages are supported: Chinese, English, Japanese, French, Russian, Portuguese, Spanish, German, Korean, and Arabic.
Translation Ignore Options
You can choose to skip translation for the following content:
- Tables
- Code
- Figures
- References
Output Formats
Multiple output combinations are supported:
- Text Output: Original MD, Translation MD, Bilingual MD, Original HTML, Translation HTML, Bilingual HTML, Translation PDF, Bilingual PDF
- Layout-Preserved Output: Original MD, Layout-preserved translation PDF, Layout-preserved bilingual PDF (original left / translation right), Layout-preserved bilingual PDF (translation left / original right)
Glossary
Custom glossaries are supported to ensure consistent translation of domain-specific terminology. You can select and update glossaries in the settings page.
After configuration, check "I have completed parsing & translation configuration" to enable the features.
Step 5: Start Using
Right-click on a PDF with a parent item to see the Doc2X menu with the following actions:
- Translate PDF to Md Notes — Translate the PDF to the target language and import as Markdown notes
- Parse PDF to Md Notes — Parse PDF content into Markdown notes in Zotero (without translation)
- Translate with Layout Preservation — Translate PDF while preserving the original layout
- Open Error Log Directory — Access plugin error logs
For notes that have already been parsed, right-click also provides:
- Doc2X: Preview Markdown — Preview the Markdown source of the note
- Doc2X: View in Web — View parse/translation results in the browser
Important Usage Notes
Large File Processing Recommendations
- Not recommended to translate PDFs with many pages (>100 pages) in Zotero
- Status updates may not be obvious during long PDF translations
- No progress updates doesn't mean translation is stuck — please be patient
- You can check real-time translation progress in the client
DeepSeek Model Special Notice
DeepSeek model takes longer during translation, please be patient.
Translation Error Handling
If you encounter translation stage errors (parsing completed and parsing pages deducted, but translation process failed):
Correct Approach:
- Select the related result in the client's left task bar
- Click "Continue Translation"
- This operation only deducts points and won't deduct parsing pages again
- In the client, use the export option in the top-right corner to export to Zotero
Incorrect Approach:
- ❌ Don't re-initiate translation in Zotero
Plugin-Client Communication
The plugin communicates with the locally running Doc2X client via SSE (Server-Sent Events). When using the plugin, ensure:
- The Doc2X client is running
- If the connection drops, the plugin will automatically attempt to reconnect
System Compatibility
| Operating System | Supported Versions | Zotero Version | Status |
|---|---|---|---|
| Windows | Win10/Win11 | Zotero 7/8 | ✅ Supported |
| Windows | Win10/Win11 | Zotero 6 | ❌ Not Supported |
| Mac | M-series Chips | Zotero 7/8 | ✅ Supported |
| Mac | Intel Chips | - | ❌ Not Yet Supported |
Issue Feedback
If you encounter any bugs or issues, please contact us through:
Frequently Asked Questions
Q: What to do when XPI file shows as corrupted?
A: Switch to Edge or Chrome browser for downloading and installation.
Q: Is it normal for translation progress to remain unchanged for long periods?
A: Yes, this is normal, especially when using DeepSeek model. Please be patient and check real-time progress in the client.
Q: How to avoid duplicate charges?
A: After translation failure, continue translation in the client rather than re-initiating in Zotero.
Q: Which Zotero versions are supported?
A: Zotero 7 / 8 is supported; Zotero 6 is not supported.
Q: Do I still need to install the Better Notes plugin?
A: No. The latest version of the plugin has completely removed the dependency on Better Notes for Zotero. No additional plugins are needed.
Q: How to clear plugin cache?
A: Click the "Clear Cache" button in the plugin settings page. This resets all settings while preserving your authorization information.
Q: What if the plugin can't connect to the Doc2X client?
A: Ensure the Doc2X client is running. The plugin automatically detects the local client port and will retry on connection failure. If it still doesn't connect, try restarting both the client and Zotero.