Skills-SIMarket
skills-si.com
Proposer une Skill
/
L’interface est localisée ; les présentations et documents des Skills sont traduits automatiquement par IA dans votre langue. Le code, les commandes, chemins et termes techniques restent en version originale, et le document de l’auteur fait foi.
Explorer les Skills
Documents · SKILL.md

docutranslate

docutranslate

Use when translating documents locally via LLM — PDF, Word, Excel, Markdown, SRT subtitles with format preservation. DocuTranslate: LLM-powered multi-format local file translation tool with MCP server support.

Independent GitHub snapshot · Automated classification · Original documentation governs

Zznlgis / opengis-skillsMIT

Documentation de la Skill

GitHub

name: docutranslate description: "Use when translating documents locally via LLM — PDF, Word, Excel, Markdown, SRT subtitles with format preservation. DocuTranslate: LLM-powered multi-format local file translation tool with MCP server support." tags:

  • ai
  • llm
  • translation
  • document
  • pdf
  • mineru
  • mcp
  • python
  • cli

项目地址： https://github.com/xunbu/docutranslate

PyPI： https://pypi.org/project/docutranslate/

官方文档： GitHub README（中/英/日/越）｜API文档：启动后 http://127.0.0.1:8010/docs（Swagger UI）

最新发布： 参见 GitHub Releases

许可证： Mozilla Public License 2.0 (MPL-2.0) 最新版本： v1.7.9（参见 PyPI）

概述

DocuTranslate 是一款基于大语言模型（LLM）的本地文件翻译工具，主打「多格式 + 保留排版 + 可编程集成」。

  • 多格式支持：pdf、docx、xlsx、md、txt、json、epub、srt、ass 等。
  • PDF 智能解析：接入 MinerU（在线或本地部署），识别学术论文中的表格、公式、代码。
  • 术语表自动生成：确保专业术语在全文中翻译一致。
  • 格式保留：docx/xlsx 翻译后保留原始格式（暂不支持旧版 doc/xls）。
  • 多 AI 平台：兼容 OpenAI 兼容协议的主流平台，支持高并发翻译与自定义提示词。
  • 多种使用形态：开箱即用的 Web UI、RESTful API、Client SDK、MCP Server，以及 Windows/Mac 便携整合包（<40MB）。

⚠️ 翻译 pdf 时会先转换为 markdown，会丢失原始版式。对版式有严格要求者请注意。

DocuTranslate 迭代很快，命令、字段与参数请以当前版本的 docutranslate --help、Web 界面、http://127.0.0.1:8010/docs 及仓库最新代码为准。

环境与安装

前置要求

  • Python 3.11+（源码/包安装方式）
  • AI 平台的 API Key（OpenAI 兼容协议）
  • 翻译 PDF 需 MinerU：在线（申请 Token）或本地部署

安装方式

# pip 安装
pip install docutranslate
# 安装 MCP 扩展
pip install "docutranslate[mcp]"

# uv 安装（推荐）
uv init
uv add docutranslate
uv add "docutranslate[mcp]"

# 源码
git clone https://github.com/xunbu/docutranslate.git
cd docutranslate
uv sync --no-dev            # uv sync --no-dev --extra mcp / --all-extras

Docker：

docker run -d -p 8010:8010 xunbu/docutranslate:latest
# 请从 GitHub Releases 获取最新标签：https://github.com/xunbu/docutranslate/releases
docker run -it -p 8010:8010 xunbu/docutranslate:latest

便携整合包： 从 GitHub Releases 下载 Windows/Mac 整合包，解压后填入 API-Key 即可使用。

Web UI 与 API 服务

docutranslate -i                       # 启动 GUI（默认仅本机访问）
docutranslate -i --host 0.0.0.0        # 允许局域网其它设备访问
docutranslate -i -p 8081               # 指定端口
docutranslate -i --cors                # 启用默认 CORS
docutranslate -i --with-mcp            # 启动 GUI 并附带 MCP SSE 端点（共享队列/端口）
  • 交互界面：http://127.0.0.1:8010（或指定端口）
  • API 文档（Swagger UI）：http://127.0.0.1:8010/docs
  • MCP SSE 端点：http://127.0.0.1:8010/mcp/sse（--with-mcp 启动时）

Client SDK（推荐入门方式）

Client 类提供简单直观的编程接口，自动识别文件类型并选择工作流：

from docutranslate.sdk import Client

client = Client(
    api_key="YOUR_API_KEY",
    base_url="https://api.openai.com/v1/",
    model_id="gpt-4o",
    to_lang="Chinese",
    concurrent=10,          # 并发请求数
)

# 1) 纯文本文件（无需 PDF 解析引擎）
result = client.translate("path/to/document.txt")
print("已保存:", result.save())

# 2) PDF（在线 MinerU，需 token）
result = client.translate(
    "path/to/document.pdf",
    convert_engine="mineru",
    mineru_token="YOUR_MINERU_TOKEN",
    formula_ocr=True,       # 公式识别
)
result.save(fmt="html")

# 3) PDF（本地部署 MinerU，适合内网/离线）
result = client.translate(
    "path/to/document.pdf",
    convert_engine="mineru_deploy",
    mineru_deploy_base_url="http://127.0.0.1:8000",
    mineru_deploy_backend="hybrid-auto-engine",
)
result.save(fmt="markdown")

# 4) Docx（保留格式）
result = client.translate("path/to/document.docx", insert_mode="replace")  # replace/append/prepend
result.save(fmt="docx")

# 5) 导出 base64（便于 API 传输）
b64 = result.export(fmt="html")

异步： 使用 client.translate_async() 支持并行多任务；result.workflow 可访问底层工作流做高级操作。

常用 Client 参数

参数类型默认说明
api_key / base_url / model_idstr-AI 平台凭证与模型
to_langstr-目标语言（如 "Chinese"、"English"）
concurrentint10并发 LLM 请求数
convert_enginestr"mineru"PDF 解析引擎：mineru / mineru_deploy
md2docx_enginestr"auto"md→docx：python / pandoc / auto / null
mineru_tokenstr-在线 MinerU token
mineru_deploy_base_urlstr-本地 MinerU 地址
skip_translateboolFalse仅解析、不翻译
chunk_sizeint3000送入 LLM 的分块大小
temperaturefloat0.3LLM 温度
timeout / retryint60 / 3超时秒数 / 失败重试次数
rpm / tpmint-每分钟请求/令牌限速

环境变量

以环境变量方式配置（便于 Docker/MCP/CI）：

环境变量说明必填
DOCUTRANSLATE_API_KEYAI 平台 API Key是
DOCUTRANSLATE_BASE_URLAI 平台 Base URL是
DOCUTRANSLATE_MODEL_ID模型 ID是
DOCUTRANSLATE_TO_LANG目标语言（默认中文）否
DOCUTRANSLATE_CONCURRENT并发请求数（默认 10）否
DOCUTRANSLATE_CONVERT_ENGINEPDF 转换引擎否
DOCUTRANSLATE_MINERU_TOKENMinerU API Token否

MCP 集成

DocuTranslate 可作为 MCP（Model Context Protocol）服务器接入 AI 助手：

docutranslate --mcp                                  # stdio 模式
docutranslate --mcp --transport sse                  # SSE 模式（默认 8000 端口）
docutranslate --mcp --transport sse --mcp-host 127.0.0.1 --mcp-port 8000
docutranslate --mcp --transport streamable-http      # Streamable HTTP 模式

uvx 免安装配置（客户端 mcpServers）：

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

SSE 模式下客户端配置端点：http://127.0.0.1:8000/mcp/sse。

典型工作流

  1. 准备：安装 DocuTranslate，准备 AI 平台 API Key（PDF 另需 MinerU token 或本地部署）。
  2. 选择形态：普通用户 → Web UI；开发者 → Client SDK / REST API / MCP。
  3. 配置模型与解析引擎：填写 base_url/model_id；PDF 选择 mineru（在线）或 mineru_deploy（本地）。
  4. 术语一致性：启用术语表自动生成，或提供自定义术语表与提示词。
  5. 翻译并导出：result.save(fmt=...) 输出 markdown/html/docx 等格式。

AI 使用建议

  • 生成 SDK 调用代码时，务必带上 base_url/model_id/to_lang；PDF 场景默认 convert_engine="mineru" 需要 mineru_token。
  • 内网/离线场景优先建议 convert_engine="mineru_deploy" + 本地 MinerU。
  • 对版式敏感的 PDF 应提醒用户「PDF→markdown 会丢失原始版式」。
  • 高并发场景配置 concurrent/rpm/tpm 做限速，避免触发平台限流。
  • 参数字段以用户当前版本的 docutranslate --help 与 /docs 为准，避免臆造 API。

常见问题（FAQ）

问题说明
PDF 翻译后版式丢失？PDF 会先转 markdown，属预期行为；对版式敏感请用其它格式或本地 MinerU。
不想暴露到局域网？默认仅本机访问；需要局域网访问才加 --host 0.0.0.0。
支持 doc/xls 吗？暂不支持旧版二进制格式，仅 docx/xlsx。
如何只解析不翻译？SDK 传 skip_translate=True。
触发平台限流？降低 concurrent，设置 rpm/tpm 限速。

参考资源

More skills to explore

Voir toutes les Skills
Skills enregistrées