[Zotero-pdf2zh] Easily Translate Zotero Literature: A Step-by-Step Guide to Configuring the pdf2zh Plugin — PDFMathTranslate

Background

#

Recently, PDFMathTranslate released a plugin compatible with Zotero. After some exploration, I was able to use it normally, so I organized this guide to share with everyone.

Project link: Zotero PDF Chinese translation plugin

Usage Steps

#

Step 1: Install or Update pdf2zh

#

For a first-time installation, use:

1

pip install pdf2zh

If it is already installed, run the following command to update it to the latest version:

1

pip install -U pdf2zh

Step 2: Download and Install the Zotero Plugin

#

Search for “pdf2zh” on the Zotero Chinese Community, or go directly to the plugin release page zotero-pdf2zh and download the plugin file ending in .xpi. You can also install it through Zotero’s plugin marketplace.

After downloading:

• Open Zotero and click Tools → Plugins;
• Drag the downloaded .xpi plugin file directly into the plugin window to install it automatically.

Step 3: Configure the Script and Related Files

#

Add the Configuration File

#

1. Create and Configure config.json

#

Create a file named config.json anywhere on your computer and fill it with the following template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
    "USE_MODELSCOPE": "0",
    "NOTO_FONT_PATH": "/app/SourceHanSerifCN-Regular.ttf",
    "translators": [
        {
            "name": "deeplx",
            "envs": {
                "DEEPLX_ENDPOINT": "http://localhost:1188/translate/",
                "DEEPLX_ACCESS_TOKEN": null
            }
        },
        {
            "name": "ollama",
            "envs": {
                "OLLAMA_HOST": "http://[redacted-ip]:11434",
                "OLLAMA_MODEL": "gemma2"
            }
        }
    ]
}

• For the font path (NOTO_FONT_PATH), I recommend using an absolute path. For specific settings, refer to: example config.json

• If you are not sure how to fill in the configuration, you can check it through the GUI:

  • Run this in the command line:

    1

    pdf2zh -i

  • In the GUI that appears, choose the corresponding translation service, such as OpenAI. Copy the information in the Option field, such as OPENAI_BASE_URL, into config.json.

    

How to view the font path on Windows: Open C:\Windows\Fonts, or press Win + i, search for “Fonts,” open “Font settings” → “Legacy font control panel,” find the corresponding font, right-click it, choose “Properties” → “Security,” and copy “Object name.” That is the font path. Note: replace \ in the path with / or \\.

2. Create and Configure server.py

#

Copy all the code from server.py, create a new file named server.py, and paste the code into it.

The parts that need to be changed are the default configuration in the script:

1
2
3
4
5

# Set the output path for translated files (temporary path, can be deleted after use)
translated_dir = "./translated/"

# Set the path to the config.json file
config_path = './config.json'

I recommend using absolute paths. For example, copy the path with Ctrl + Shift + C:

1
2

translated_dir = "D:/python_project/python1/zotero-pdf2zh/translated/pdf2zh"
config_path = "D:/python_project/python1/zotero-pdf2zh/config.json"

3. Configure the Zotero Plugin

#

Open Zotero and go to Edit → Settings → pdf2zh:

• The “translation configuration” content must match the path in server.py.
• If you switch translation services, first confirm that config.json is correct, and then adjust the plugin configuration here.
• I recommend checking “Rename item to short title” to prevent translation failure caused by overly long file paths.
• Choose the “default generated files” options according to your own needs.

How to Use the Plugin to Translate PDFs

#

1. First run the server.py script:

1

python server.py

2. Then find the literature PDF you want to translate in Zotero and right-click it:

• Choose PDF2zh: Translate PDF to start translation;
• By default, two files are generated:
  • dual: original and translated pages alternate one by one;
  • mono: translated-only version.

    

The plugin also provides two other useful functions:

• PDF2zh: Cut PDF
  • Cuts a two-column PDF into a single-column PDF, which is more suitable for reading on mobile devices.
  • The generated single-column PDF filename contains the cut marker.
• PDF2zh: Chinese-English side-by-side
  • Processes the translated dual file into a Chinese-and-English two-column comparison format.
  • The generated filename contains the compare marker.

Common Error Handling

#

If the server response fails, it is usually caused by an error in the configuration file (config.json) or script (server.py). Please carefully check the following:

1. Python and dependency environment

   • Use Python 3.10–3.12.
   • Make sure pdf2zh, flask, pypdf, pdfminer.six==20250416, and other dependencies are installed correctly.

2. Tool version matching

   • Recommended: pdf2zh v1.9.6.
   • Recommended: zotero-pdf2zh plugin v2.4.1 or later.

3. Valid and existing paths

   • The font path is correct and exists.
   • All paths should preferably be absolute paths.
   • Avoid Chinese characters, spaces, or special characters in paths.
   • Replace \ in paths uniformly with / or \\.

4. Configuration file settings

   • config.json should be in the same directory as server.py, or passed in as a full path through parameters.
   • The JSON format must be valid. Pay attention to closing punctuation, such as quotation marks and commas.
   • The translators field should contain the translation service you enabled and provide complete credentials.

5. Python script execution

   • The startup port of server.py should match the Zotero plugin settings.
   • Before starting the script, I recommend using cd to enter the directory where the script is located.
   • If you change the port, update the port configuration in the plugin at the same time.

6. Zotero plugin settings

   • The translation parameters in the plugin must correspond to config.json and the script configuration.
   • The output path should be simple and should avoid exceeding the operating system’s path-length limit.

7. Translation-service suggestions and fallback strategy

   • Prefer Bing or Google Translate first, because their setup is simpler and their responses are faster.
   • If translation fails, switch to Bing first to verify the configuration file, then try other services such as Deepseek or SiliconFlow.

8. Port and dependency conflicts

   • If the port is occupied, try changing the default port in server.py.
   • If you encounter dependency errors, reinstall the corresponding libraries according to the officially recommended versions.

Click here to watch the video version of this article