Metadata-Version: 2.4
Name: mdtrans
Version: 0.1.0
Summary: Convert PDFs with MinerU and translate the generated Markdown into Simplified Chinese.
Author-email: kelf <kelfvin@163.com>
Keywords: llm,markdown,mineru,pdf,translation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: langchain-openai>=0.3.35
Requires-Dist: langchain>=0.3.27
Requires-Dist: markdown-it-py>=4.0.0
Requires-Dist: mineru[core,vllm]>=3.0.9
Requires-Dist: tiktoken>=0.12.0
Description-Content-Type: text/markdown

# MDTrans

[简体中文](./README.zh.md) | 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

```bash
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.

```toml
[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:

```bash
export OPENAI_API_KEY="your-api-key"
```

```bash
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
