DocuTranslate

DocuTranslate is a lightweight local file translation tool powered by Large Language Models (LLMs).

Key Capabilities:

• Multi-format Support: Translates pdf, docx, xlsx, md, txt, json, epub, srt, ass, and more.
• Glossary Generation: Automatically creates glossaries to ensure terminology consistency.
• Advanced PDF Parsing: Uses mineru (online or local) to recognize and translate tables, formulas, and code blocks in academic papers.
• JSON Translation: Supports translating specific values in JSON using jsonpath-ng syntax.
• Format Preservation: Maintains original formatting for docx and xlsx files.
• High Performance: Supports asynchronous operations and parallel multitasking.
• Deployment Options: Provides a Web UI, RESTful API, and MCP (Model Context Protocol) server support. It also offers portable packages for Windows and Mac.

Note on PDFs: When translating pdf files, they are converted to markdown first, which may result in the loss of the original layout.

For fine-grained control, you can bypass the Client and use specific Workflow classes. All workflows follow a standard lifecycle:

1. Create a TranslatorConfig (LLM settings).
2. Create a WorkflowConfig (Workflow-specific settings).
3. Instantiate the Workflow object.
4. Call workflow.read_path(file_path).
5. Call await workflow.translate_async() (or workflow.translate() for synchronous).
6. Use workflow.save_as_*() or workflow.export_to_*() to retrieve results.

Available Workflows

import asyncio
from docutranslate.workflow.md_based_workflow import MarkdownBasedWorkflow, MarkdownBasedWorkflowConfig
from docutranslate.converter.x2md.converter_mineru import ConverterMineruConfig
from docutranslate.translator.ai_translator.md_translator import MDTranslatorConfig
from docutranslate.exporter.md.md2html_exporter import MD2HTMLExporterConfig

async def main():
    # 1. LLM Configuration
    translator_config = MDTranslatorConfig(
        base_url="https://open.bigmodel.cn/api/paas/v4",
        api_key="YOUR_ZHIPU_API_KEY",
        model_id="glm-4-air",
        to_lang="English",
        chunk_size=3000,
        concurrent=10,
    )

    # 2. Converter Configuration (MinerU)
    converter_config = ConverterMineruConfig(
        mineru_token="YOUR_MINERU_TOKEN",
        formula_ocr=True
    )

    # 3. Workflow Configuration
    workflow_config = MarkdownBasedWorkflowConfig(
        convert_engine="mineru",
        converter_config=converter_config,
        translator_config=translator_config,
        html_exporter_config=MD2HTMLExporterConfig(cdn=True)
    )

    # 4. Execution
    workflow = MarkdownBasedWorkflow(config=workflow_config)
    workflow.read_path("path/to/your/document.pdf")
    await workflow.translate_async()

    # 5. Output
    workflow.save_as_html(name="translated_document.html")
    workflow.save_as_markdown(name="translated_document.md")

if __name__ == "__main__":
    asyncio.run(main())

When translating PDF files, you can choose between an online MinerU service or a locally deployed MinerU instance.

Option A: Online MinerU

Requires a mineru_token obtained from https://mineru.net/apiManage/token.

Option B: Local MinerU Deployment

Recommended for internal or offline environments. Requires a running MinerU service (see https://github.com/opendatalab/MinerU). You must provide the mineru_deploy_base_url.

# Option A: Online MinerU
result = client.translate(
    "path/to/your/document.pdf",
    convert_engine="mineru",
    mineru_token="YOUR_MINERU_TOKEN",
    formula_ocr=True,
)

# Option B: Local MinerU
result = client.translate(
    "path/to/your/document.pdf",
    convert_engine="mineru_deploy",
    mineru_deploy_base_url="http://127.0.0.1:8000",
    mineru_deploy_backend="hybrid-auto-engine",
)

For desktop clients like Claude Desktop or Windsurf, use the Stdio transport mode. It is highly recommended to use the absolute path to the Python interpreter within your virtual environment to ensure all dependencies are available.

Option 1: Using uvx (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": "中文",
        "DOCUTRANSLATE_CONCURRENT": "10",
        "DOCUTRANSLATE_CONVERT_ENGINE": "mineru",
        "DOCUTRANSLATE_MINERU_TOKEN": "your-mineru-token"
      }
    }
  }
}

Option 2: Using Virtual Environment Python (Recommended)

Use the full path to your virtual environment's Python executable.

Linux/macOS:

{
  "mcpServers": {
    "docutranslate": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "docutranslate.mcp"],
      "env": { ... }
    }
  }
}

Windows:

{
  "mcpServers": {
    "docutranslate": {
      "command": "C:\\path\\to\\your\\venv\\Scripts\\python.exe",
      "args": ["-m", "docutranslate.mcp"],
      "env": { ... }
    }
  }
}

Option 3: Using docutranslate in PATH

If the command is already in your system PATH:

{
  "mcpServers": {
    "docutranslate": {
      "command": "docutranslate",
      "args": ["--mcp"],
      "env": { ... }
    }
  }
}

DocuTranslate provides a Web Interface and a RESTful API. Use the docutranslate -i command with various flags to configure the service.

Common CLI Flags for Starting Service

• docutranslate -i: Start GUI (default local access).
• docutranslate -i --host 0.0.0.0: Allow access from other devices on your LAN.
• docutranslate -i -p 8081: Specify a custom port number.
• docutranslate -i --cors: Enable default CORS settings.
• docutranslate -i --with-mcp: Start GUI with an MCP SSE endpoint (shares queue and port).

Starting MCP Server Modes

• docutranslate --mcp: Start MCP server in stdio mode.
• docutranslate --mcp --transport sse: Start MCP server in SSE mode.
• docutranslate --mcp --transport sse --mcp-host <HOST> --mcp-port <PORT>: Start MCP server in SSE mode with specific host/port.
• docutranslate --mcp --transport streamable-http: Start MCP server in Streamable HTTP mode.

Accessing the Service

• Web Interface: Visit http://127.0.0.1:8010 (or your specified port).
• API Documentation (Swagger): Visit http://127.0.0.1:8010/docs.
• MCP SSE Endpoint:
  • If started with --with-mcp: http://127.0.0.1:8010/mcp/sse
  • If started with --mcp: http://127.0.0.1:8000/mcp/sse

docutranslate -i --host 0.0.0.0 -p 8081 --cors

Stdio mode is recommended for clients like Claude Desktop or Windsurf.

Important: Always use the Python interpreter from your virtual environment in your MCP configuration to ensure all dependencies are available.

Option 1: Using uvx (No installation required)

Use this configuration in your MCP settings:

{
  "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 2: Using Virtual Environment Python

Provide the absolute path to the Python executable in your virtual environment:

Linux/macOS:

{
  "mcpServers": {
    "docutranslate": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "docutranslate.mcp"],
      "env": { ... }
    }
  }
}

Windows:

{
  "mcpServers": {
    "docutranslate": {
      "command": "C:\\path\\to\\your\\venv\\Scripts\\python.exe",
      "args": ["-m", "docutranslate.mcp"],
      "env": { ... }
    }
  }
}

Option 3: Using docutranslate in PATH

If the command is already in your system PATH:

{
  "mcpServers": {
    "docutranslate": {
      "command": "docutranslate",
      "args": ["--mcp"],
      "env": { ... }
    }
  }
}