DocuTranslate: LLM File Translation That Converts PDF to Markdown First

The gap DocuTranslate fills: translation inside document structure

Pasting a chapter into a chat window works until the document has structure. A DOCX with styles, an XLSX with cells, an EPUB with chapters, or a subtitle file with timecodes all lose something in that round trip. DocuTranslate targets that gap. The README describes it as a lightweight local file translation tool based on Large Language Models, and the format list is the point: pdf, docx, xlsx, md, txt, json, epub, srt, ass. The audience is people who translate documents rather than strings: someone working through a novel, a thesis, or a batch of subtitles who wants the file to come back as a file. The tool runs locally and talks to an AI platform you configure, so the document does not have to pass through a third-party translation service. That matters for unpublished manuscripts and internal papers. It is not a translation engine itself. It is the layer that parses a document, sends text to a model, and reassembles the result.

How translation actually flows through the tool

The mechanism visible in the README is a pipeline: parse the source format, extract translatable text, send it to an LLM endpoint, write the translated text back into the original container. For docx and xlsx the README claims format preservation while noting that the older doc and xls formats are not supported. For JSON the tool does not translate the whole file; it translates values selected by path using jsonpath-ng syntax, which keeps keys and structure intact. PDF is the outlier. The README states plainly that when translating pdf, it is first converted to markdown and this will lose the original layout, and it tells users with strict layout requirements to take note. Conversion is handled by mineru, which the README says can run online or locally deployed, and which handles tables, formulas and code common in academic papers. That is a real architectural decision: the PDF is reduced to a markdown stream, translated as text, and never reassembled into a page-faithful PDF. The glossary feature is the other structural piece. The README describes automatic glossary generation to ensure term alignment, which addresses the failure mode where a model renders the same term three ways across three chapters. Concurrency is exposed as a knob, defaulting to 10 parallel requests, so throughput is bounded by your API rate limit rather than by the parser.

Running it: pip, uv, docker, and the -i flag

Installation is conventional Python. With pip: pip install docutranslate, then docutranslate -i to start the interface. With uv: uv add docutranslate and uv run --no-dev docutranslate -i. From git: git clone the repository, then uv sync --no-dev. Docker is a single command: docker run -d -p 8010:8010 xunbu/docutranslate:latest. The -i flag starts the web UI and REST API, and the README lists the modifiers that matter in practice: docutranslate -i --host 0.0.0.0 exposes it to the LAN, docutranslate -i -p 8081 changes the port, docutranslate -i --cors enables default CORS settings, and docutranslate -i --with-mcp adds an MCP SSE endpoint on the same port. The interactive interface is served at http://127.0.0.1:8010, and Swagger documentation sits at /docs on the same port. Configuration for MCP use runs through environment variables: DOCUTRANSLATE_API_KEY, DOCUTRANSLATE_BASE_URL and DOCUTRANSLATE_MODEL_ID are required, while DOCUTRANSLATE_TO_LANG defaults to Chinese, DOCUTRANSLATE_CONCURRENT defaults to 10, DOCUTRANSLATE_CONVERT_ENGINE selects the PDF conversion engine, and DOCUTRANSLATE_MINERU_TOKEN supplies the MinerU API token. The README also gives a uvx configuration that runs the MCP server without a prior install, passing docutranslate[mcp] as the package source. Note that the README's usage examples section is truncated in the supplied material, so the per-format command syntax beyond the service flags is not something I can confirm.

The PDF trade-off is the decision point

Most document translation tools make one promise and hide one cost. DocuTranslate states its cost in a blockquote near the top of the README: PDF becomes markdown, and layout is lost. If you are translating a paper to read it, that is fine, and the mineru conversion of tables, formulas and code is a reasonable trade. If you are translating a contract, a slide deck exported to PDF, or a scanned form where position carries meaning, this is the wrong tool, and no amount of model quality fixes it. The second limitation is format coverage. The README is explicit that doc and xls are not supported, only docx and xlsx. Legacy files need conversion before they enter the pipeline, and that conversion is on you. Third, the tool is a client, not a model. Every quality property people attribute to translation tools, terminology consistency, register, handling of proper nouns, is delegated to whatever endpoint you point DOCUTRANSLATE_BASE_URL at. The glossary feature constrains the model, but it does not replace it. A cheap model with a good glossary will still produce flat prose, and the README offers no evaluation of model choices. Finally, the concurrency default of 10 is a starting point, not a tuned value. Against a rate-limited endpoint it will produce errors, and the material does not describe retry or backoff behaviour, so that is something to verify against your provider rather than assume.

Where it sits against a document-parsing library like MinerU alone

The closest comparison in the material is not another translation tool but the component DocuTranslate already depends on. MinerU is a PDF parsing and conversion system. Used directly, it turns a PDF into markdown, and you then send that markdown wherever you like. DocuTranslate wraps that conversion and adds the translation layer: format dispatch across docx, xlsx, json, epub, srt and ass, a web UI, a REST API, an MCP server, glossary generation, and concurrent request handling. The difference in approach is scope. MinerU answers what is in this PDF. DocuTranslate answers what does this document say in another language, and it accepts formats MinerU does not touch. If your only input is PDFs and you want to control the translation prompt and the reassembly yourself, calling MinerU directly and scripting the model call gives you more control and one less dependency. If your inputs are mixed, or you want the LAN multi-user interface and the MCP endpoint that lets an agent invoke translation as a tool, the wrapper is doing work you would otherwise write. The honest framing is that DocuTranslate is a workflow layer, and its value scales with how many of those workflow pieces you would have to build.

MCP, LAN use, and the packaging claim

The MCP integration is the most distinctive feature in the README and the one most likely to drive adoption now. DocuTranslate can run as an MCP server in three transports: stdio via docutranslate --mcp, SSE via docutranslate --mcp --transport sse with --mcp-host and --mcp-port, and streamable HTTP via docutranslate --mcp --transport streamable-http. The README notes that --with-mcp shares the queue and port with the GUI, so an agent and a human can use the same instance. The SSE endpoint is documented at http://127.0.0.1:8010/mcp/sse when started with --with-mcp, and http://127.0.0.1:8000/mcp/sse when started with --mcp. The LAN and multi-user support claim follows from the --host 0.0.0.0 flag and the shared queue. Be careful with that combination: exposing the service to a network means the API key configured on the server is available to anyone who can reach the port, and the README's --cors flag is described only as enabling default CORS settings, with no detail on what those defaults are. The packaging claim, that Windows and Mac portable packages are under 40MB, is a distribution statement rather than a runtime property, and the material does not say whether those packages bundle model access or require the same environment variables.

Licence and the cost of keeping up

DocuTranslate is MPL-2.0. That is a file-level copyleft licence: modifications to covered files must be made available under the same licence, while larger works that combine it with other code can be distributed under different terms. For most users running the tool internally, the practical effect is limited. For anyone embedding it in a product or shipping a modified build, the obligation attaches to the modified files, and the specifics are worth reading in the licence text rather than inferring from a summary. I am not giving legal advice here. On maintenance, the release cadence visible in the material is steady: v1.7.7, v1.7.8 and v1.7.9 appear between late June and early September, with the newest pushed the same day as its release. That is frequent enough that pinning a version for production is reasonable. The upgrade cost is not zero, because the tool sits between two moving parts: the document formats it parses and the model endpoints it calls. A change in either can break a working setup. Environment variables are the stable interface, so configuration through DOCUTRANSLATE_* keys is likely to survive version bumps better than relying on internal module paths. The README's usage examples are truncated in the material I have, which itself is a small caution: confirm the current CLI surface against the version you install rather than against a cached README.

Editorial conclusion

Adopt DocuTranslate if you already have an OpenAI-compatible endpoint and your documents are text-first: markdown, DOCX, XLSX, JSON, EPUB or subtitle files, where formatting is preserved for docx and xlsx. Do not adopt it if your PDFs must keep their original layout, since the README states PDF translation converts to markdown first and loses layout, and doc and xls are not supported. Verify three things before committing: that your chosen PDF conversion engine (mineru, online or local) handles your document class, that your model produces acceptable glossary output, and that your MPL-2.0 obligations fit how you plan to redistribute the tool.

Official sources

1. Issues
2. License: MPL-2.0
3. README
4. Releases
5. xunbu/docutranslate on GitHub