mdtrans 0.1.0

Convert PDFs with MinerU and translate the generated Markdown into Simplified Chinese.

MDTrans

简体中文 | English

Overview

Convert any English PDF document into Chinese Markdown.

MDTrans supports both digitally generated PDFs and scanned PDFs. It preserves the document structure from the source PDF, including text, headings, lists, and tables, and translates the content into Simplified Chinese. Because translation is performed with larger LLM context windows, MDTrans usually achieves better document-level consistency and overall translation quality than typical short-context translation tools. The final translated Markdown file is written beside the original Markdown with a .zh.md suffix.

How It Works

MDTrans first calls the official mineru CLI from an async Python subprocess to convert a PDF into Markdown, including scanned-document workflows supported by MinerU, then uses LangChain and an OpenAI-compatible chat model to translate the generated Markdown into Simplified Chinese with larger document context rather than fragmented sentence-by-sentence translation.

Requirements

• A GPU capable of running MinerU, ideally with at least 16 GB of VRAM

Installation

uv tool install mdtrans

Configuration

The configuration file is located at ~/.config/mdtrans/config.toml. If it does not exist, MDTrans creates a template for you on first run.

[llm]
base_url = "https://api.deepseek.com"
model = "deepseek-chat"
context_window = 64000
max_output_tokens = 8000
max_chunk_tokens = 5000

The mimo-flash model from Xiaomi is a good default choice when available, with a strong balance between translation quality and speed.

Usage

MDTrans relies on an OpenAI-compatible API, so you must export OPENAI_API_KEY before running it:

export OPENAI_API_KEY="your-api-key"

mdtrans /path/to/input.pdf /path/to/output-dir

The tool runs in this order:

1. Accept the source PDF path as the first positional argument
2. Accept the output directory as the second positional argument
3. Run mineru -p <selected-pdf> -o <output-dir> -b hybrid-auto-engine
4. Discover the generated Markdown files under the chosen output directory
5. Write translated Chinese copies as *.zh.md beside the original Markdown files