Advanced

Advanced > Advanced (current)

Table of Contents

• Command Line Args
• Rate Limiting Configuration Guide
• Partial translation
• Specify source and target languages
• Translate wih exceptions
• Custom prompt
• Custom configuration
• Skip clean
• Translation cache
• Deployment as a public services
• Authentication and welcome page
• Glossary Support

Command Line Args

Execute the translation command in the command line to generate the translated document example-mono.pdf and the bilingual document example-dual.pdf in the current working directory. Use Google as the default translation service. More support translation services can find HERE.

In the following table, we list all advanced options for reference:

Args

GUI Args

⬆️ Back to top

Rate Limiting Configuration Guide

When using translation services, proper rate limiting configuration is crucial to avoid API errors and optimize performance. This guide explains how to configure --qps and --pool-max-worker parameters based on different upstream service limitations.

RPM (Requests Per Minute) Rate Limiting

When the upstream service has RPM limitations, use the following calculation:

Calculation Formula: - qps = floor(rpm / 60) - pool_size = qps * 10

Example: If your translation service has a limit of 600 RPM: - qps = floor(600 / 60) = 10 - pool_size = 10 * 10 = 100

pdf2zh example.pdf --qps 10 --pool-max-worker 100

Concurrent Connection Limiting

When the upstream service has concurrent connection limitations (like GLM official service), use this approach:

Calculation Formula: - pool_size = max(floor(0.9 * official_concurrent_limit), official_concurrent_limit - 20) - qps = pool_size

Example: If your translation service allows 50 concurrent connections: - pool_size = max(floor(0.9 * 50), 50 - 20) = max(45, 30) = 45 - qps = 45

pdf2zh example.pdf --qps 45 --pool-max-worker 45

Best Practices

⬆️ Back to top

Partial translation

Use the --pages parameter to translate a portion of a document.

• If the page numbers are consecutive, you can write it like this:

pdf2zh_next example.pdf --pages 1-3

pdf2zh_next example.pdf --pages 25-

• If the pages are not consecutive, you can use a comma , to separate them.

For example, if you want to translate the first and third pages, you can use the following command:

pdf2zh_next example.pdf --pages "1,3"

• If the pages include both consecutive and non-consecutive ranges, you can also connect them with a comma, like this:

pdf2zh_next example.pdf --pages "1,3,10-20,25-"

This command will translate the first page, the third page, pages 10-20, and all pages from 25 to the end.

⬆️ Back to top

Specify source and target languages

See Google Languages Codes, DeepL Languages Codes

pdf2zh_next example.pdf --lang-in en -lang-out ja

⬆️ Back to top

Translate wih exceptions

Use regex to specify formula fonts and characters that need to be preserved:

pdf2zh_next example.pdf --formular-font-pattern "(CM[^RT].*|MS.*|.*Ital)" --formular-char-pattern "(\(|\||\)|\+|=|\d|[\u0080-\ufaff])"

Preserve Latex, Mono, Code, Italic, Symbol and Math fonts by default:

pdf2zh_next example.pdf --formular-font-pattern "(CM[^R]|MS.M|XY|MT|BL|RM|EU|LA|RS|LINE|LCIRCLE|TeX-|rsfs|txsy|wasy|stmary|.*Mono|.*Code|.*Ital|.*Sym|.*Math)"

⬆️ Back to top

Custom prompt

Custom system prompt for translation. It is mainly used to add the '/no_think' instruction of Qwen 3 in the prompt.

pdf2zh_next example.pdf --custom-system-prompt "/no_think You are a professional and reliable machine translation engine responsible for translating the input text into zh_CN.When translating, strictly follow the instructions below to ensure translation quality and preserve all formatting, tags, and placeholders:"

⬆️ Back to top

Custom configuration

There are multiple ways to modify and import the configuration file.

• Modifying Configuration via Command Line Arguments

For most cases, you can directly pass your desired settings through command line arguments. Please refer to Command Line Args for more information.

For example, if you want to enable a GUI window, you can use the following command:

pdf2zh_next --gui

• Modifying Configuration via Environment Variables

You can replace the -- in command line arguments with PDF2ZH_, connect parameters using =, and replace - with _ as environment variables.

For example, if you want to enable a GUI window, you can use the following command:

PDF2ZH_GUI=TRUE pdf2zh_next

• User-Specified Configuration File

You can specify a configuration file using the command line argument below:

pdf2zh_next --config-file '/path/config.toml'

If you are unsure about the config file format, please refer to the default configuration file described below.

• Default Configuration File

The default configuration file is located at ~/.config/pdf2zh. Please do not modify the configuration files in the default directory. It is strongly recommended to refer to this configuration file's content and use User-Specified Configuration File to implement your own configuration file.

⬆️ Back to top

Skip clean

When this parameter is set to True, the PDF cleaning step will be skipped, which can improve compatibility and avoid some font processing issues.

Usage:

pdf2zh_next example.pdf --skip-clean

Or using environment variables:

PDF2ZH_SKIP_CLEAN=TRUE pdf2zh_next example.pdf

Translation cache

PDFMathTranslate caches translated texts to increase speed and avoid unnecessary API calls for same contents. You can use --ignore-cache option to ignore translation cache and force retranslation.

pdf2zh_next example.pdf --ignore-cache

⬆️ Back to top

Deployment as a public services

When deploying a pdf2zh GUI on public services, you should modify the configuration file as described below.

A usable configuration is as follows:

[basic]
gui = true

[gui_settings]
enabled_services = "Bing,OpenAI"
disable_gui_sensitive_input = true
disable_config_auto_save = true

⬆️ Back to top

Authentication and welcome page

When using Authentication and welcome page to specify which user to use Web UI and custom the login page:

example auth.txt Each line contains two elements, username, and password, separated by a comma.

admin,123456
user1,password1
user2,abc123
guest,guest123
test,test123

example welcome.html

<!DOCTYPE html>
<html>
<head>
    <title>Simple HTML</title>
</head>
<body>
    <h1>Hello, World!</h1>
    <p>Welcome to my simple HTML page.</p>
</body>
</html>

A usable configuration is as follows:

[basic]
gui = true

[gui_settings]
auth_file = "/path/to/auth/file"
welcome_page = "/path/to/welcome/html/file"

⬆️ Back to top

Glossary Support

PDFMathTranslate supports the glossary table. The glossary tables file should be csv file. There are three columns in file. Here is a demo glossary file:

For CLI user: You can use multiple files for glossary. And different files should be split by ,.

pdf2zh_next example.pdf --glossaries "glossary1.csv,glossary2.csv,glossary3.csv"

For WebUI user:

You can upload your own glossary file now. After you uploaded the file, you can check them by click their name and the content shows below.

⬆️ Back to top