RetainPDF

1. What is RetainPDF?

RetainPDF is an app that translates PDF files while keeping the layout intact: math formulas, tables, multiple columns and images stay where they belong. Most translation tools spit out a lump of plain text and wreck the formulas and formatting. RetainPDF targets scientific papers, textbooks and technical documents, including image-based or scanned PDFs. The result is a translated PDF, a Markdown version or a ZIP bundle, plus a reader that places the original beside the translation so you can compare.

It is free and open source (MIT license). It runs as a desktop app (Windows, macOS, Linux) or as a web page you host on your own machine using Docker.

Know this before installing: RetainPDF cannot translate on its own. It calls two online services and you must bring your own access keys (tokens, API keys) for them: one that recognizes the text in a PDF (OCR) and one AI model that does the translating. Those services may bill you for usage; they are not part of the project. Also, according to the documentation and source code, the default target language of the translation is Simplified Chinese. The documentation does not clearly say whether Vietnamese or other languages can be chosen, so test with a small file first.

A good fit if:

• You read many foreign-language papers or technical books and want translations that keep formulas and layout.
• You have, or are willing to create, accounts with the OCR and AI services listed in section 2.
• You can work with an interface whose buttons and labels are mostly Chinese (the source code shows Chinese labels).

Not a fit if:

• You want to translate fully offline. Both OCR and translation use online services.
• You only need a few sentences or one paragraph translated. An ordinary translator is quicker.
• You need Vietnamese output and do not want to test to find out.

2. What you need

Computer:

• Windows, macOS or Linux (a .deb file, for Ubuntu/Debian). The latest version at the time of writing is v4.2.5 (19 September 2026).
• Installer sizes: about 235 MB (Windows), 290 MB (macOS), 237 MB (Linux).
• The documentation gives no minimum specification for the desktop app. For the Docker setup, the project recommends at least 4 CPU cores, 8 GB of RAM and 10 GB of free disk; no graphics card is needed.
• The macOS build is made on Apple Silicon tooling. The documentation does not promise it runs on Intel Macs.

Access keys (needed before you can translate):

Service	Used for	Where to get it
PaddleOCR (default) through Baidu AI Studio	Recognizing text and layout in the PDF	Access Token at https://aistudio.baidu.com/account/accessToken
Or MinerU	Alternative to Paddle	API Token at https://mineru.net/apiManage/docs
An OpenAI-compatible AI model, for example DeepSeek	Translating the text	API key, for example at https://platform.deepseek.com/api_keys

The app has ready-made presets for DeepSeek, Qwen, Anthropic, OpenAI and Zhipu. The pages for getting keys from these services may be in Chinese or may require registration and a top-up. Check the terms and pricing on each service's official page before you use it.

Extra software (only for the Docker route):

• Docker (a tool that runs apps in isolated "containers", so you do not install each component by hand): https://docs.docker.com/get-started/get-docker/
• Git (a tool for downloading source code): https://git-scm.com/downloads

3. Step-by-step installation

The easiest route is the desktop app (Steps 1 to 3). Docker in Step 4 is for people who want to run it as a web service.

Step 1: Download the installer

Open https://github.com/wxyhgk/retain-pdf/releases/latest and download the file for your system:

• Windows: RetainPDF-Windows-4.2.5-Setup.exe
• macOS: RetainPDF-Mac-4.2.5.dmg
• Linux: RetainPDF-Linux-4.2.5.deb

The page also has SHA256SUMS.txt, which you can use to check that your download is intact.

Step 2: Install on each system

Windows: double-click RetainPDF-Windows-4.2.5-Setup.exe and follow the installer. Open RetainPDF from the Start menu.

macOS:

1. Double-click the .dmg and drag RetainPDF into the Applications folder.
2. Open RetainPDF. If macOS says the app is "damaged" (per the README, this is how macOS reacts to an app downloaded from the internet), open Terminal and run:

sudo xattr -r -d com.apple.quarantine /Applications/RetainPDF.app

Enter your Mac password when asked, then open the app again.

Linux (Ubuntu/Debian): open a terminal in the folder with the downloaded file and run:

sudo apt install ./RetainPDF-Linux-4.2.5.deb

What success looks like: RetainPDF shows up in your applications list and opens its main window, which has a library (a bookshelf) for managing your files.

Step 3: Enter your access keys

The app needs an OCR key and an AI-model key before it can translate. In the web version this dialog is at the top right, labelled "API 配置" (API settings); the desktop app has a similar place to enter them. You fill in:

1. OCR provider: leave the default PaddleOCR and paste its Access Token, or choose MinerU and paste its API Token.
2. Translation model: choose a provider (for example DeepSeek) and paste the API key. The address and model name are pre-filled per provider (DeepSeek uses https://api.deepseek.com/v1).
3. Press the check button next to each field (the buttons labelled "检测", which means "check") to confirm the key works.

What success looks like: each check reports a successful connection. If it says the key is invalid or expired, see section 5.

Step 4 (alternative): Run it with Docker

Use this if you want RetainPDF as a web page on your own computer or server. Install Docker and Git (section 2), then check:

docker --version
docker compose version

Then download the code and start it:

git clone https://github.com/wxyhgk/retain-pdf.git
cd retain-pdf/ops/deployment/docker/delivery
docker compose up -d

When it has started, open http://127.0.0.1:40001 in your browser.

What success looks like: the RetainPDF page appears. If the key fields are empty, enter your OCR key and model key in the API settings dialog as in Step 3.

Note: by default the service listens only on 127.0.0.1, meaning only your own machine can reach it. The project's documentation says to allow outside access only after adding your own login protection (for example Basic Auth in NGINX). Do not expose it to the internet without that.

4. First use

Try a short PDF of a few pages:

1. Open RetainPDF and make sure the OCR key and model key are entered correctly (Step 3).
2. Add your PDF to the app (the import area of the library). The official documentation does not describe every button, so names may differ slightly between versions.
3. Start the translation. The app works in stages: recognizing the text, translating, then laying the pages out again. You can watch progress on screen.
4. When it finishes, open the result. You can download the translated PDF, a Markdown version or a ZIP bundle.

What success looks like: the translated PDF keeps the positions of figures, tables and formulas, and the text in the blocks has been replaced by the translation. Use the side-by-side reader to compare the original with the result.

A few more features, from the README:

You want to	Where
Compare original and translation	The side-by-side reader (shows both versions next to each other)
Read as Markdown, keeping formulas and images	The Markdown reader
Ask questions about the document, with page citations	The AI assistant in the reader (uses the AI model you configured)
Manage many files and mark favorites	The library

File size limits: the project's Docker bundle recommends about 200 MB and 300 pages per file at most; the interface shows the limit actually in force.

5. Common problems and fixes

Symptom	Cause	Fix
macOS says the app is "damaged"	macOS puts a quarantine flag on apps downloaded from the internet	Move the app to Applications and run sudo xattr -r -d com.apple.quarantine /Applications/RetainPDF.app from Step 2
The key check fails, or translation stops right away	The OCR key or model key is wrong or expired, or the account is out of credit	Re-check the key on the service's own page; use the check button ("检测") next to the key field; top up if the service requires it
It reports "翻译接口检测失败" (translation interface check failed)	Wrong API address, wrong key, or the network blocks the service	Check the API address against the provider's and check your connection to that service
A translation job fails midway and retrying fails too	Some failures have been reported by users on GitHub (for example issue #132 about the translation stage failing often, and #134 about parts of a PDF not being translated)	Try a shorter file, switch provider or model, update to the latest version, or look and report at https://github.com/wxyhgk/retain-pdf/issues
The file is refused as too large or too many pages	It exceeds the size or page limit of your installation	Split the PDF; the interface shows the limit in force
Docker: docker compose up -d cannot pull the images	The machine cannot reach Docker Hub	Check your network; the project states it needs access to Docker Hub, MinerU and the model API
Docker: http://127.0.0.1:40001 will not open	The containers are still starting, or the port is taken	Wait a few tens of seconds; check status with docker compose ps; stop whatever uses port 40001, or set the WEB_PORT variable (for example WEB_PORT=40002 docker compose up -d)

6. Uninstalling and updating

Updating

• Desktop: download the new version from https://github.com/wxyhgk/retain-pdf/releases/latest and install it over the old one.
• Docker: go to retain-pdf/ops/deployment/docker/delivery and run:

docker compose pull
docker compose up -d

Uninstalling

• Windows: open the installed apps list in Settings, find RetainPDF and uninstall.
• macOS: drag RetainPDF from Applications to the Trash.
• Linux: find the package name with the command below, then remove it with sudo apt remove <package name>.

dpkg -l | grep -i retain

• Docker: in the delivery folder, run this to stop and remove the containers:

docker compose down

To also delete the data Docker stored (your jobs and translation results), add the -v flag:

docker compose down -v

Translated PDFs that you already downloaded to your computer are not deleted when you uninstall.

7. Frequently asked questions

Does RetainPDF cost anything? The software is free and open source (MIT). But translating uses outside OCR and AI-model services, which may bill you by usage. Check each service's pricing page.

Does it need the internet? Yes. It needs a connection to reach the OCR and AI-model services; the Docker route also pulls images from Docker Hub.

Are my files sent anywhere? By the project's design, the PDF goes to the OCR provider you choose (PaddleOCR or MinerU) and the text goes to the AI-model provider for translation. If your documents are sensitive, read those services' data policies first.

Can it translate into Vietnamese? By default the translation is Simplified Chinese (per the source code). The official documentation does not say whether other target languages can be selected. Test with a small file and look at the interface, or ask at https://github.com/wxyhgk/retain-pdf/issues

Will it run on a weak machine? The heavy work (OCR and translation) is done by outside services; the project says it mainly uses CPU, RAM and network, and needs no graphics card. For the Docker setup the suggestion is 4 CPU cores and 8 GB of RAM or more.