Example 2: Translate PDF files (requires mineru_token or local deployment)

Prerequisites and Detailed Configuration

Basic installation

pip install docutranslate

Install mcp extension

pip install docutranslate[mcp]

docutranslate -i

#docutranslate -i --with-mcp ```

Basic installation

uv add docutranslate

Install mcp extension

uv add docutranslate[mcp]

uv run --no-dev docutranslate -i

#uv run --no-dev docutranslate -i --with-mcp ```

Using docker

```bash docker run -d -p 8010:8010 xunbu/docutranslate:latest

docker run -it -p 8010:8010 xunbu/docutranslate:latest

docker run -it -p 8010:8010 xunbu/docutranslate:v1.5.4

```

uvx Configuration (No Installation Required)

{
  "mcpServers": {
    "docutranslate": {
      "command": "uvx",
      "args": ["--from", "docutranslate[mcp]", "docutranslate", "--mcp"],
      "env": {
        "DOCUTRANSLATE_API_KEY": "sk-xxxxxx",
        "DOCUTRANSLATE_BASE_URL": "https://api.openai.com/v1",
        "DOCUTRANSLATE_MODEL_ID": "gpt-4o",
        "DOCUTRANSLATE_TO_LANG": "Chinese",
        "DOCUTRANSLATE_CONCURRENT": "10",
        "DOCUTRANSLATE_CONVERT_ENGINE": "mineru",
        "DOCUTRANSLATE_MINERU_TOKEN": "your-mineru-token"
      }
    }
  }
}

Option B: Use locally deployed MinerU (recommended for intranet/offline)

2.2. Locally Deployed MinerU Service

For offline/intranet environments, you can use locally deployed minerU. Set mineru_deploy_base_url to your minerU API endpoint.

Client SDK:

from docutranslate.sdk import Client

client = Client(
    api_key="YOUR_LLM_API_KEY",
    model_id="llama3",
    to_lang="Chinese",
    convert_engine="mineru_deploy",
    mineru_deploy_base_url="http://127.0.0.1:8000",  # Your minerU API address
)
result = client.translate("document.pdf")
result.save(fmt="markdown")

Quick Start

Usage Examples

Example 1: Translate plain text files (no PDF parsing engine needed)

result = client.translate("path/to/your/document.txt") print(f"Translation complete! Saved to: {result.save()}")

Example 3: Translate Docx files (preserve formatting)

result = client.translate( "path/to/your/document.docx", insert_mode="replace", # replace/append/prepend ) result.save(fmt="docx") # Save as docx format

Example 4: Export as base64 encoded string (for API transmission)

base64_content = result.export(fmt="html") print(f"Exported content length: {len(base64_content)}")

Initialize environment

uv init

Initialize environment

git clone https://github.com/xunbu/docutranslate.git

cd docutranslate

uv sync --no-dev

MCP Configuration

DocuTranslate can be used as an MCP (Model Context Protocol) server. For detailed documentation, see MCP Documentation.

Supported Environment Variables

SSE Mode Configuration

First start the MCP server in SSE mode:

docutranslate --mcp --transport sse --mcp-host 127.0.0.1 --mcp-port 8000

Then configure the SSE endpoint in your client: http://127.0.0.1:8000/mcp/sse

Initialize the client with your AI platform settings

client = Client( api_key="YOUR_OPENAI_API_KEY", # or any other AI platform API key base_url="https://api.openai.com/v1/", model_id="gpt-4o", to_lang="Chinese", concurrent=10, # Number of concurrent requests )

Option A: Use online MinerU (token required: https://mineru.net/apiManage/token)

result = client.translate( "path/to/your/document.pdf", convert_engine="mineru", mineru_token="YOUR_MINERU_TOKEN", # Replace with your MinerU Token formula_ocr=True, # Enable formula recognition ) result.save(fmt="html")

1. Create TranslatorConfig (LLM settings)

2. Create WorkflowConfig (workflow settings)

TXT: from docutranslate.workflow.txt_workflow import TXTWorkflow, TXTWorkflowConfig

JSON: from docutranslate.workflow.json_workflow import JsonWorkflow, JsonWorkflowConfig

DOCX: from docutranslate.workflow.docx_workflow import DocxWorkflow, DocxWorkflowConfig

XLSX: from docutranslate.workflow.xlsx_workflow import XlsxWorkflow, XlsxWorkflowConfig

EPUB: from docutranslate.workflow.epub_workflow import EpubWorkflow, EpubWorkflowConfig

HTML: from docutranslate.workflow.html_workflow import HtmlWorkflow, HtmlWorkflowConfig

SRT: from docutranslate.workflow.srt_workflow import SrtWorkflow, SrtWorkflowConfig

ASS: from docutranslate.workflow.ass_workflow import AssWorkflow, AssWorkflowConfig

```

Key config options: - insert_mode: "replace", "append", or "prepend" (for docx/xlsx/html/epub) - json_paths: JSONPath expressions for JSON translation (e.g., ["$.*", "$.name"]) - separator: Text separator for "append" / "prepend" modes

Start Web UI and API Service

For ease of use, DocuTranslate provides a fully functional Web Interface and RESTful API.

Start the Service:

  docutranslate -i                           (Start GUI, default local access)
  docutranslate -i --host 0.0.0.0            (Allow access from other devices on LAN)
  docutranslate -i -p 8081                   (Specify port number)
  docutranslate -i --cors                    (Enable default CORS settings)
  docutranslate -i --with-mcp                (Start GUI with MCP SSE endpoint, shared queue, shared port)
  docutranslate --mcp                         (Start MCP server, stdio mode)
  docutranslate --mcp --transport sse         (Start MCP server, SSE mode)
  docutranslate --mcp --transport sse --mcp-host MCP_HOST   --mcp-port MCP_PORT  (Start MCP server, SSE mode)
  docutranslate --mcp --transport streamable-http  (Start MCP server, Streamable HTTP mode)

• Interactive Interface: After starting the service, please visit http://127.0.0.1:8010 (or your specified port) in your browser.
• API Documentation: Full API documentation (Swagger UI) is located at http://127.0.0.1:8010/docs.
• MCP: SSE service endpoint is at http://127.0.0.1:8010/mcp/sse (started with --with-mcp) or http://127.0.0.1:8000/mcp/sse (started with --mcp)

Using the Simple Client SDK (Recommended)

The easiest way to get started is using the Client class, which provides a simple and intuitive API for translation:

```python from docutranslate.sdk import Client

First start local MinerU service, reference: https://github.com/opendatalab/MinerU

result = client.translate( "path/to/your/document.pdf", convert_engine="mineru_deploy", mineru_deploy_base_url="http://127.0.0.1:8000", # Your local MinerU address mineru_deploy_backend="hybrid-auto-engine", # Backend type ) result.save(fmt="markdown")

Using Workflow API (For Advanced Control)

For more control, use the Workflow API directly. Each workflow follows the same pattern:

```python

1. Get Large Model API Key

Translation functionality relies on Large Language Models. You need to obtain a base_url, api_key, and model_id from the corresponding AI platform.

Recommended Models: Volcengine's doubao-seed-1-6-flash, doubao-seed-1-6 series, Zhipu's glm-4-flash, Alibaba Cloud's qwen-plus, qwen-flash, Deepseek's deepseek-chat, etc.

302.AI 👈 Register via this link to get $1 free credit.

Integration Packages

For users who want to get started quickly, we provide integration packages on GitHub Releases. Simply download, unzip, and enter your AI platform API-Key to start using it.

You can also access the underlying workflow for advanced operations

workflow = result.workflow

**Client Features:**
- **Auto-detection**: Automatically detects file type and selects the appropriate workflow
- **Flexible Configuration**: Override any default settings per translation call
- **Multiple Output Options**: Save to disk or export as Base64 string
- **Async Support**: Use `translate_async()` for concurrent translation tasks

#### Client SDK Parameters

| Parameter | Type | Default | Description |
|:---|:---|:---|:---|
| **api_key** | `str` | - | AI platform API key |
| **base_url** | `str` | - | AI platform base URL (e.g., `https://api.openai.com/v1/`) |
| **model_id** | `str` | - | Model ID to use for translation |
| **to_lang** | `str` | - | Target language (e.g., `"Chinese"`, `"English"`, `"Japanese"`) |
| **concurrent** | `int` | 10 | Number of concurrent LLM requests |
| **convert_engine** | `str` | `"mineru"` | PDF parsing engine: `"mineru"`, `"mineru_deploy"` |
| **md2docx_engine** | `str` | `"auto"` | Markdown to Docx engine: `"python"` (pure Python), `"pandoc"` (use Pandoc), `"auto"` (use Pandoc if installed, otherwise Python), `null` (do not generate docx) |
| **mineru_deploy_base_url** | `str` | - | Local minerU API address (when `convert_engine="mineru_deploy"`) |
| **mineru_deploy_parse_method** | `str` | `"auto"` | Local minerU parsing method: `"auto"`, `"txt"`, `"ocr"` |
| **mineru_deploy_table_enable** | `bool` | `True` | Enable table recognition for local minerU |
| **mineru_token** | `str` | - | minerU API token (when using online minerU) |
| **skip_translate** | `bool` | `False` | Skip translation, only parse document |
| **output_dir** | `str` | `"./output"` | Default output directory for `save()` |
| **chunk_size** | `int` | 3000 | Text chunk size for LLM processing |
| **temperature** | `float` | 0.3 | LLM temperature parameter |
| **timeout** | `int` | 60 | Request timeout in seconds |
| **retry** | `int` | 3 | Number of retry attempts on failure |
| **provider** | `str` | `"auto"` | AI provider type (auto, openai, azure, etc.) |
| **force_json** | `bool` | `False` | Force JSON output mode |
| **rpm** | `int` | - | Requests per minute limit |
| **tpm** | `int` | - | Tokens per minute limit |
| **extra_body** | `str` | - | Additional request body parameters in JSON string format, will be merged into API request |
| **thinking** | `str` | `"auto"` | Thinking mode: `"auto"`, `"none"`, `"block"` |
| **custom_prompt** | `str` | - | Custom prompt for translation |
| **system_proxy_enable** | `bool` | `False` | Enable system proxy |
| **insert_mode** | `str` | `"replace"` | Docx/Xlsx/Txt insertion mode: `"replace"`, `"append"`, `"prepend"` |
| **separator** | `str` | `"\n"` | Text separator for append/prepend modes |
| **segment_mode** | `str` | `"line"` | Segmentation mode: `"line"`, `"paragraph"`, `"none"` |
| **translate_regions** | `list` | - | Excel translation regions (e.g., `"Sheet1!A1:B10"`) |
| **model_version** | `str` | `"vlm"` | MinerU model version: `"pipeline"`, `"vlm"` |
| **formula_ocr** | `bool` | `True` | Enable formula OCR for PDF parsing |
| **code_ocr** | `bool` | `True` | Enable code OCR for PDF parsing |
| **mineru_deploy_backend** | `str` | `"hybrid-auto-engine"` | MinerU local backend: `"pipeline"`, `"vlm-auto-engine"`, `"vlm-http-client"`, `"hybrid-auto-engine"`, `"hybrid-http-client"` |
| **mineru_deploy_formula_enable** | `bool` | `True` | Enable formula recognition for local MinerU |
| **mineru_deploy_start_page_id** | `int` | 0 | Start page ID for local MinerU parsing |
| **mineru_deploy_end_page_id** | `int` | 99999 | End page ID for local MinerU parsing |
| **mineru_deploy_lang_list** | `list` | - | Language list for local MinerU parsing |
| **mineru_deploy_server_url** | `str` | - | MinerU local server URL |
| **json_paths** | `list` | - | JSONPath expressions for JSON translation (e.g., `"$.data.*"`) |
| **glossary_generate_enable** | `bool` | - | Enable auto glossary generation |
| **glossary_dict** | `dict` | - | Glossary dictionary (e.g., `{"Jobs": "Steve Jobs"}`) |
| **glossary_agent_config** | `dict` | - | Glossary agent configuration |

#### Result Methods

| Method | Parameters | Description |
|:---|:---|:---|
| **save()** | `output_dir`, `name`, `fmt` | Save translation result to disk |
| **export()** | `fmt` | Export as Base64 encoded string |
| **supported_formats** | - | Get list of supported output formats |
| **workflow** | - | Access underlying workflow object |

async def translate_multiple(): client = Client( api_key="YOUR_API_KEY", base_url="https://api.openai.com/v1/", model_id="gpt-4o", to_lang="Chinese", )

# Translate multiple files concurrently files = ["doc1.pdf", "doc2.docx", "notes.txt"] results = await asyncio.gather( *[client.translate_async(f) for f in files] )

for r in results: print(f"Saved: {r.save()}")

asyncio.run(translate_multiple()) ```

3. Create Workflow instance

4. workflow.read_path(file)

5. await workflow.translate_async()

6. workflow.save_as_*(name=...) or export_to_*(...)

#### Available Workflows and Output Methods

| Workflow | Inputs | save_as_* | export_to_* | Key Config Options |
|:---|:---|:---|:---|:---|
| **MarkdownBasedWorkflow** | `.pdf`, `.docx`, `.md`, `.png`, `.jpg` | `html`, `markdown`, `markdown_zip`, `docx` | `html`, `markdown`, `markdown_zip`, `docx` | `convert_engine`, `md2docx_engine`, `translator_config` |
| **TXTWorkflow** | `.txt` | `txt`, `html` | `txt`, `html` | `translator_config` |
| **JsonWorkflow** | `.json` | `json`, `html` | `json`, `html` | `translator_config`, `json_paths` |
| **DocxWorkflow** | `.docx` | `docx`, `html` | `docx`, `html` | `translator_config`, `insert_mode` |
| **XlsxWorkflow** | `.xlsx`, `.csv` | `xlsx`, `html` | `xlsx`, `html` | `translator_config`, `insert_mode` |
| **SrtWorkflow** | `.srt` | `srt`, `html` | `srt`, `html` | `translator_config` |
| **EpubWorkflow** | `.epub` | `epub`, `html` | `epub`, `html` | `translator_config`, `insert_mode` |
| **HtmlWorkflow** | `.html`, `.htm` | `html` | `html` | `translator_config`, `insert_mode` |
| **AssWorkflow** | `.ass` | `ass`, `html` | `ass`, `html` | `translator_config` |

#### Key Configuration Options

**Common TranslatorConfig Options:**

| Option | Type | Default | Description |
|:---|:---|:---|:---|
| `base_url` | `str` | - | AI platform base URL |
| `api_key` | `str` | - | AI platform API key |
| `model_id` | `str` | - | Model ID |
| `to_lang` | `str` | - | Target language |
| `chunk_size` | `int` | 3000 | Text chunk size |
| `concurrent` | `int` | 10 | Concurrent requests |
| `temperature` | `float` | 0.3 | LLM temperature |
| `timeout` | `int` | 60 | Request timeout (seconds) |
| `retry` | `int` | 3 | Retry attempts |

**Format-Specific Options:**

| Option | Applicable Workflows | Description |
|:---|:---|:---|
| `insert_mode` | Docx, Xlsx, Html, Epub | `"replace"` (default), `"append"`, `"prepend"` |
| `json_paths` | Json | JSONPath expressions (e.g., `["$.*", "$.name"]`) |
| `separator` | Docx, Xlsx, Html, Epub | Text separator for append/prepend modes |
| `convert_engine` | MarkdownBased | `"mineru"` (default), `"mineru_deploy"` |

#### Example 1: Translate a PDF File (Using `MarkdownBasedWorkflow`)

This is the most common use case. We will use the `minerU` engine to convert the PDF to Markdown, and then translate it using an LLM. This example uses asynchronous execution.

async def main(): # 1. Build Translator Configuration translator_config = MDTranslatorConfig( base_url="https://open.bigmodel.cn/api/paas/v4", # AI Platform Base URL api_key="YOUR_ZHIPU_API_KEY", # AI Platform API Key model_id="glm-4-air", # Model ID to_lang="English", # Target Language chunk_size=3000, # Text chunk size concurrent=10, # Concurrency level # glossary_generate_enable=True, # Enable auto-glossary generation # glossary_dict={"Jobs":"Steve Jobs"}, # Pass in a glossary dictionary # system_proxy_enable=True, # Enable system proxy )

# 2. Build Converter Configuration (Using minerU) converter_config = ConverterMineruConfig( mineru_token="YOUR_MINERU_TOKEN", # Your minerU Token formula_ocr=True # Enable formula recognition )

# 3. Build Main Workflow Configuration workflow_config = MarkdownBasedWorkflowConfig( convert_engine="mineru", # Specify parsing engine converter_config=converter_config, # Pass converter config translator_config=translator_config, # Pass translator config html_exporter_config=MD2HTMLExporterConfig(cdn=True) # HTML export config )

# 4. Instantiate Workflow workflow = MarkdownBasedWorkflow(config=workflow_config)

# 5. Read file and execute translation print("Starting to read and translate file...") workflow.read_path("path/to/your/document.pdf") await workflow.translate_async() # Or use synchronous method # workflow.translate() print("Translation complete!")

# 6. Save results workflow.save_as_html(name="translated_document.html") workflow.save_as_markdown_zip(name="translated_document.zip") workflow.save_as_markdown(name="translated_document.md") # Markdown with embedded images print("Files saved to ./output folder.")

# Or get content strings directly html_content = workflow.export_to_html() html_content = workflow.export_to_markdown() # print(html_content)

if name == "main": asyncio.run(main()) ```

Other Workflows

All workflows follow the same pattern. Import the corresponding config and workflow, then configure:

```python

FAQ

Q: Output is in original language? A: Check logs for errors. Usually due to exhausted API credits or network issues.

Q: Port 8010 occupied? A: Use docutranslate -i -p 8011 or set DOCUTRANSLATE_PORT=8011.

Q: Scanned PDFs supported? A: Yes, use mineru engine with OCR capabilities.

Q: Use in intranet/offline? A: Yes. Local translation can be achieved by deploying a local LLM (Ollama/LM Studio/VLLM, etc.). If you need to parse PDFs locally, you also need to deploy MinerU locally.

Q: PDF cache mechanism? A: MarkdownBasedWorkflow caches parsing results in memory (last 10 parses). Configure via DOCUTRANSLATE_CACHE_NUM.

Q: Enable proxy? A: Set system_proxy_enable=True in TranslatorConfig.