Docutranslate

<p align="center"> <img src="./DocuTranslate.png" alt="Project Logo" style="width: 150px"> </p> <h1 align="center">DocuTranslate</h1> <p align="center"> <a href="https://github.com/xunbu/docutranslate/stargazers"><img src="https://img.shields.io/github/stars/xunbu/docutranslate?style=flat-square&logo=github&color=blue" alt="GitHub stars"></a> <a href="https://github.com/xunbu/docutranslate/releases"><img src="https://img.shields.io/github/downloads/xunbu/docutranslate/total?logo=github&style=flat-square" alt="GitHub Downloads"></a> <a href="https://pypi.org/project/docutranslate/"><img src="https://img.shields.io/pypi/v/docutranslate?style=flat-square" alt="PyPI version"></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white&style=flat-square" alt="Python Version"></a> <a href="./LICENSE"><img src="https://img.shields.io/github/license/xunbu/docutranslate?style=flat-square" alt="License"></a> </p> <p align="center"> <a href="/README_ZH.md"><strong>简体中文</strong></a> / <a href="/README.md"><strong>English</strong></a> / <a href="/README_JP.md"><strong>日本語</strong></a> / <a href="/README_VI.md"><strong>Tiếng Việt</strong></a> </p> <p align="center"> A lightweight local file translation tool based on Large Language Models. </p>

• ✅ Support Multiple Formats: Translates pdf, docx, xlsx, md, txt, json, epub, srt, ass, and more.
• ✅ Auto-Generate Glossary: Supports automatic glossary generation to ensure term alignment.
• ✅ PDF Table, Formula, Code Recognition: Leverages docling and mineru PDF parsing engines to recognize and translate tables, formulas, and code often found in academic papers.
• ✅ JSON Translation: Supports specifying values to translate within JSON using paths (jsonpath-ng syntax).
• ✅ Word/Excel Format Preservation: Supports docx and xlsx files (currently does not support doc or xls) while maintaining original formatting.
• ✅ Multi-AI Platform Support: Supports most AI platforms, allowing for high-performance concurrent AI translation with custom prompts.
• ✅ Async Support: Designed for high-performance scenarios, providing full asynchronous support and interfaces for parallel multi-tasking.
• ✅ LAN & Multi-user Support: Supports simultaneous use by multiple users within a local area network (LAN).
• ✅ Interactive Web Interface: Provides an out-of-the-box Web UI and RESTful API for easy integration and usage.
• ✅ Compact, Portable Packages: Windows and Mac portable packages under 40MB (versions that do not use docling for local PDF parsing).

When translating pdf, it is first converted to markdown. This will lose the original layout. Users with strict layout requirements should take note.

QQ Community Group: 1047781902 1081128602

UI Interface:

Paper Translation:

Novel Translation:

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.

• DocuTranslate: Standard version. Uses minerU (online or locally deployed) for PDF parsing. Supports local minerU API calls. (Recommended)
• DocuTranslate_full: Full version. Includes the built-in docling local PDF parsing engine. Choose this version if you need offline PDF parsing without minerU.

Quick Start

Using pip

# Basic installation
pip install docutranslate

# Install mcp extension
pip install docutranslate[mcp]

# Install docling extension
pip install docutranslate[docling]

docutranslate -i

#docutranslate -i --with-mcp

Using uv

# Initialize environment
uv init

# Basic installation
uv add docutranslate

# Install mcp extension
uv add docutranslate[mcp]

# Install docling extension
uv add docutranslate[docling]

uv run --no-dev docutranslate -i

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

Using git

# Initialize environment
git clone https://github.com/xunbu/docutranslate.git

cd docutranslate

uv sync --no-dev
# uv sync --no-dev --extra mcp
# uv sync --no-dev --extra docling
# uv sync --no-dev --all-extras

Using docker

docker run -d -p 8010:8010 xunbu/docutranslate:latest #does not support docling
# docker run -it -p 8010:8010 xunbu/docutranslate:latest
# docker run -it -p 8010:8010 xunbu/docutranslate:v1.5.4

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)

MCP Configuration

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

Supported Environment Variables

| Environment Variable | Description | Required | |---------------------|-------------|----------| | DOCUTRANSLATE_API_KEY | AI platform API key | Yes | | DOCUTRANSLATE_BASE_URL | AI platform base URL | Yes | | DOCUTRANSLATE_MODEL_ID | Model ID | Yes | | DOCUTRANSLATE_TO_LANG | Target language (default: Chinese) | No | | DOCUTRANSLATE_CONCURRENT | Concurrent requests (default: 10) | No | | DOCUTRANSLATE_CONVERT_ENGINE | PDF conversion engine | No | | DOCUTRANSLATE_MINERU_TOKEN | MinerU API Token | No |

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"
      }
    }
  }
}

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

Usage Examples

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:

from docutranslate.sdk import Client

# 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
)

# 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 2: Translate PDF files (requires mineru_token or local deployment)
# 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")

# Option B: Use locally deployed MinerU (recommended for intranet/offline)
# 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")

# 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)}")

# 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 | - | A