Important
This repository contains an unofficial Codex-enhanced v1.9.11 branch. It adds a local Codex CLI translation backend and scientific-PDF layout fixes; it is not an official PDFMathTranslate or OpenAI release. See the Chinese usage and attribution guide and the Windows desktop app guide.
The ready-to-use package is for Windows 10/11 x64 and does not require Python.
- Recommended: download the Windows EXE installer with offline layout assets
- Open the latest release page and SHA-256 checksums
- Read the detailed Chinese desktop guide
Quick start:
- Download and run
PDFMathTranslate-Codex-Setup-win64.exe. The installer creates a Start menu shortcut and an uninstaller. - Launch PDFMathTranslate Codex Studio and click 登录 Codex inside the app. Complete the official browser sign-in; the app updates the login status automatically.
- Upload a PDF, choose languages and pages, then click Translate.
- Under 关于与更新, use 检查更新 and 下载并安装更新 for future releases. Your account, settings and translation cache are retained.
- Bundle official stable Codex CLI 0.163.0 so the default executable supports current models such as
gpt-6-luna. The CLI archive is pinned by SHA-256 in the release workflow. - Select multiple PDFs and translate them in displayed order. Completed mono/bilingual downloads remain available if a later file fails. Stop halts the queue; retrying the same files/settings in the current session skips completed outputs unless Ignore cache is selected.
- Show structured model/access rejections directly instead of retrying them into an opaque
RetryError. The model documentation now distinguishes official IDs, CLI versions and account availability.
- Continue ChatGPT translations when the website virtualizes older turns, including the sixth batch and later. Recover an existing pending batch before sending newly planned work.
- Preserve the original failure from PDF Form objects. Fix
Textfont names being mistaken for TeX math fonts, which left some Nature abstracts and body paragraphs untranslated. - Keep numbered institution addresses translatable and compact footnotes readable. Validate the reported paper's first page through actual ChatGPT translation, PDF rendering and a cached repeat without additional submissions.
- Keep the first ChatGPT reply bound to its submitted message while the website assigns a permanent conversation URL. Persist the observed
local-chatgpt:client ID so live replies remain readable after the address changes and across later batches. - Recover a closed setup tab only when its task has no submission history. Preserve existing pending tasks across the observed English/Chinese effort labels, including
Highand高, rather than starting another chat. - Report completed empty replies explicitly. Recovery does not regenerate or resend automatically; regenerate the response in its original chat only when you intend to request a new answer.
- Fix ChatGPT reasoning-effort selection in background PDF tabs. Chrome could ignore the slider's keyboard input even though the browser connection and model list were available, causing a false synchronization error before translation started.
- Keep slider movement and menu dismissal inside the translation tab, with the existing position, label, model, and conversation checks.
- Support hotfix version tags in release builds and future update checks. Users on codex.5 should download the new EXE manually, because that version's updater does not recognize
.5.1tags. Install over the existing application to retain settings and documents.
- In-app Codex account status, browser/device-code login, and login cancellation.
- Adjustable batch concurrency (default 4), a 2× concurrency option, and an independent Codex Fast mode switch. Double concurrency does not guarantee half the elapsed time; Fast mode can consume more account allowance and requires model/account support.
- Completed pages appear during standard translation, including cross-page paragraph handling. The full PDF replaces the page previews when final file generation completes. The experimental BabelDOC workflow still shows its PDF after completion.
- Remaining time uses a rolling range from actually completed pages, excludes the first cold-start sample and waits for sufficient observations. Font processing and final PDF writing are shown as a separate stage.
- A Windows EXE installer and explicit in-app GitHub updates, with size and SHA-256 verification before installation. Translation must finish or be cancelled before updating.
The release includes the official stable Codex CLI 0.163.0 program so a separate
Python or Codex installation is unnecessary. It does not include an account,
subscription, free quota, login credentials, API keys, user PDFs, or translation
caches. The desktop interface is bound to 127.0.0.1, but text is sent to the
translation provider you select; Codex requests are sent to OpenAI according to
the account that signs in. See the official OpenAI Codex CLI documentation
for account and sign-in details.
These field rules apply to desktop releases codex.5 through codex.5.4. The program passes an explicit model ID unchanged to codex exec --model; it has no model-name allowlist or automatic model substitution.
| Field | Behavior |
|---|---|
CODEX_BIN |
Blank or codex prefers the bundled CLI before CODEX_CLI_PATH, PATH, and the desktop CLI. To use another installed version, enter its full executable path and check that exact binary with --version. |
CODEX_PROFILE |
Usually blank. A selected profile and configuration handling depend on the chosen CLI; the supported fast path ignores user configuration and rules. |
CODEX_MODEL |
Exact model ID, or blank to omit --model. Automatic selection is not pinned to a model or synchronized with the desktop model picker. |
CODEX_REASONING_EFFORT |
Defaults to low, including an empty field. It explicitly overrides the CLI/profile reasoning default. The backend accepts none, low, medium, high, xhigh, and max, but not ultra. |
CODEX_TIMEOUT |
Defaults to 120 seconds. Increasing it cannot resolve an HTTP 400 model rejection. |
| Model | Exact ID |
|---|---|
| GPT-6 Luna | gpt-6-luna |
| GPT-6.1 Sol | gpt-6.1-sol |
| GPT-6 Sol | gpt-6-sol |
| GPT-6 Astra | gpt-6-astra |
| Previous-generation GPT-5.6 Sol / Terra / Luna | gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna |
GPT-6 Luna is an official Codex model and supports reasoning through max. Use the full hyphenated ID, not gpt6luna or luna. See the Luna model specification and Codex model availability. GPT-6 Astra does not support explicit none.
codex.5.4 bundles official stable CLI 0.163.0; keep CODEX_BIN=codex to use it. Earlier codex.5.3 installers bundle 0.145.0. The official September 23 changelog records the Sol/Luna catalog addition in CLI 0.156.1. A local comparison on October 18 found that 0.145.0 rejected gpt-6-luna + max with HTTP 400, while official stable 0.163.0 translated a short text successfully with the same account and settings. This identifies the older CLI as a compatibility issue in that environment, rather than proving Luna or Max unavailable in general. The compatibility comparison uses a short request; PDF and queue checks are described in the release notes.
On codex.5.3 or earlier, upgrade the application to codex.5.4 or point CODEX_BIN to a current official CLI. Updating the CLI on PATH alone does not override the bundled executable. Check account/workspace access if the current CLI still rejects the request. RetryError is a retry wrapper, not the underlying reason. Starting with codex.5.4, structured model/access rejections stop immediately with their original message.
For ChatGPT sign-in, the old gpt-5.4 / gpt-5.4-mini, Spark, and gpt-5.5 entries have retired; consult the linked Codex guide instead of relying on an old local catalog. API-key availability and billing follow separate rules. The ChatGPT chat service uses its web model picker, not these CLI IDs.
PDF scientific paper translation and bilingual comparison.
- 📊 Preserve formulas, charts, table of contents, and annotations (preview).
- 🌐 Support multiple languages, and diverse translation services.
- 🤖 Provides commandline tool, interactive user interface, and Docker
For problems specific to this Codex-enhanced fork, use this fork's GitHub Issues. For upstream PDFMathTranslate discussions, use the upstream project.
For details on how to contribute, please consult the Contribution Guide.
- [May 9, 2025] pdf2zh 2.0 Preview Version #586: The Windows ZIP file and Docker image are now available.
Note
2.0 Moved to a new repository under the organization: PDFMathTranslate/PDFMathTranslate-next
Version 2.0 official release has been published.
- [Mar. 3, 2025] Experimental support for the new backend BabelDOC WebUI added as an experimental option (by @awwaawwa)
- [Feb. 22 2025] Better release CI and well-packaged windows-amd64 exe (by @awwaawwa)
- [Dec. 24 2024] The translator now supports local models on Xinference (by @imClumsyPanda)
- [Dec. 19 2024] Non-PDF/A documents are now supported using
-cp(by @reycn) - [Dec. 13 2024] Additional support for backend by (by @YadominJinta)
- [Dec. 10 2024] The translator now supports OpenAI models on Azure (by @yidasanqian)
You can try our application out using either of the following demos:
- Public free service online without installation (recommended).
- Immersive Translate - BabelDOC 1000 free pages per month. (recommended)
- Demo hosted on HuggingFace
- Demo hosted on ModelScope without installation.
Note that the computing resources of the demo are limited, so please avoid abusing them.
For different use cases, we provide distinct methods to use our program:
1. UV install
-
Python installed (3.10 <= version <= 3.12)
-
Install our package:
pip install uv uv tool install --python 3.12 pdf2zh
-
Execute translation, files generated in current working directory:
pdf2zh document.pdf
2. Windows exe
-
Download
PDFMathTranslate-Codex-win64-with-assets.zipfrom this fork's latest release. -
Extract the complete archive. To use Codex, double-click
Login-Codex.cmdonce and complete sign-in. -
Double-click
PDFMathTranslate-Codex.exe.
The package includes the pinned official Codex CLI program and BabelDOC offline
assets. pdf2zh.exe is also included for the classic browser UI and command-line
use. No account or login credential is bundled.
3. Graphic user interface
-
Python installed (3.10 <= version <= 3.12)
-
Install our package:
pip install pdf2zh-
Start using in browser:
pdf2zh -i
-
If your browser has not been started automatically, goto
http://localhost:7860/
See documentation for GUI for more details.
4. Docker
-
Pull and run:
docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh
-
Open in browser:
http://localhost:7860/
For docker deployment on cloud service:
5. Zotero Plugin
See Zotero PDF2zh for more details.
6. Commandline
-
Python installed (3.10 <= version <= 3.12)
-
Install our package:
pip install pdf2zh
-
Execute translation, files generated in current working directory:
pdf2zh document.pdf
Tip
-
If you're using Windows and cannot open the file after downloading, please install vc_redist.x64.exe and try again.
-
If you cannot access Docker Hub, please try the image on GitHub Container Registry.
docker pull ghcr.io/byaidu/pdfmathtranslate
docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslateThe present program needs an AI model(wybxc/DocLayout-YOLO-DocStructBench-onnx) before working and some users are not able to download due to network issues. If you have a problem with downloading this model, we provide a workaround using the following environment variable:
set HF_ENDPOINT=https://hf-mirror.comFor PowerShell user:
$env:HF_ENDPOINT = https://hf-mirror.comIf the solution does not work to you / you encountered other issues, please refer to frequently asked questions.
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:
For detailed explanations, please refer to our document about Advanced Usage for a full list of each option.
For downstream applications, please refer to our document about API Details for further information about:
- Python API, how to use the program in other Python programs
- HTTP API, how to communicate with a server with the program installed
-
Parse layout with DocLayNet based models, PaddleX, PaperMage, SAM2
-
Fix page rotation, table of contents, format of lists
-
Fix pixel formula in old papers
-
Async retry except KeyboardInterrupt
-
Knuth–Plass algorithm for western languages
-
Support non-PDF/A files
-
Immersive Translation sponsors monthly Pro membership redemption codes for active contributors to this project, see details at: CONTRIBUTOR_REWARD.md
-
New backend: BabelDOC
-
Document merging: PyMuPDF
-
Document parsing: Pdfminer.six
-
Document extraction: MinerU
-
Document Preview: Gradio PDF
-
Multi-threaded translation: MathTranslate
-
Layout parsing: DocLayout-YOLO
-
Document standard: PDF Explained, PDF Cheat Sheets
-
Multilingual Font: Go Noto Universal
