DocuTranslate: Dateiformate per LLM übersetzen, mit einer klaren Grenze bei PDF
文档（小说、论文、字幕）翻译工具（支持 pdf/word/excel/json/epub/srt...）Document (Novel, Thesis, Subtitle) Translation Tool (Supports pdf/word/excel/json/epub/srt...)
Auf einen Blick
- Was ist das?
- DocuTranslate ist ein lokales Python-Werkzeug, das pdf, docx, xlsx, md, txt, json, epub, srt und ass über eine konfigurierbare LLM-Schnittstelle übersetzt. Der interessante Teil ist die Dokumentkonvertierung, nicht das Modell. Der problematische Teil ist ebenfalls die Konvertierung.
- Für wen ist es gedacht?
- Wer docx, xlsx, epub oder srt mit einem eigenen API-Key übersetzen will und bereit ist, die Qualität der Zielsprache selbst zu prüfen, findet hier ein schlankes Werkzeug mit Web-UI, REST-API und MCP-Anbindung. Wer layouttreue PDF-Ausgaben braucht, sollte DocuTranslate nicht als Lösung einplanen: das README sagt ausdrücklich, dass die Konvertierung nach Markdown das Original-Layout verliert.
- Darf ich es kommerziell nutzen?
- Ja, unter Bedingungen. MPL-2.0 ist eine Lizenz mit schwachem Copyleft: Sie dürfen sie in kommerzieller und proprietärer Software verwenden, müssen aber Änderungen an ihren eigenen Dateien unter derselben Lizenz veröffentlichen, wenn Sie sie weitergeben.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 12 Tagen.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich Python, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 15. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Welches Problem DocuTranslate löst und für wen es gebaut ist
Der übliche Weg, ein Dokument zu übersetzen, besteht darin, den Text herauszukopieren, in ein Chatfenster zu werfen und das Ergebnis zurück in die Datei zu kleben. Das funktioniert bei einem Absatz. Bei einer 200-seitigen Dissertation, einer xlsx-Tabelle mit mehreren Blättern oder einer srt-Datei mit Zeitstempeln bricht es sofort zusammen. DocuTranslate setzt genau an dieser Stelle an: es liest das Quelldokument, zerlegt es in übersetzbare Einheiten, schickt diese an ein LLM und setzt das Ergebnis in ein Zieldokument zurück.
Die Zielgruppe lässt sich aus der Formatliste ablesen. pdf, docx und xlsx deuten auf wissenschaftliches Arbeiten hin, epub auf Belletristik, srt und ass auf Untertitelarbeit. Das README nennt entsprechend Beispiele für Aufsätze und Romane. Wer nur gelegentlich einen kurzen Text übersetzt, braucht dieses Werkzeug nicht. Wer regelmäßig dieselbe Dokumentenklasse durch eine Pipeline schickt, schon.
Bemerkenswert ist die Reihenfolge der Entscheidungen im Projekt. Das README beginnt nicht mit dem Modell, sondern mit den Formaten und der Format-Erhaltung. Das Modell ist austauschbar, die Datei nicht.
Der eigentliche Mechanismus: Konvertierung, Segmentierung, Rückbau
DocuTranslate ist kein Übersetzer im engeren Sinn, sondern eine Konvertierungs- und Zustellschicht um ein LLM herum. Der Datenfluss hat drei Stufen. Zuerst wird das Eingabeformat in eine Zwischendarstellung gebracht. Bei pdf ist diese Zwischendarstellung Markdown, wie das README in einem eigenen Hinweisblock festhält. Bei docx und xlsx bleibt die Struktur erhalten, laut README inklusive der ursprünglichen Formatierung. Bei json wird nicht das ganze Dokument übersetzt, sondern nur die Werte, die über Pfade in der Syntax von jsonpath-ng ausgewählt wurden.
In der zweiten Stufe geht es um das Modell. DocuTranslate spricht laut README mit den meisten KI-Plattformen, also über eine konfigurierbare Basis-URL und einen API-Key, nicht über eine fest verdrahtete Anbieter-Bindung. Übersetzt wird asynchron und mit einstellbarer Nebenläufigkeit. Der Standardwert für DOCUTRANSLATE_CONCURRENT liegt bei 10 gleichzeitigen Anfragen. Dazu kommt eine Glossar-Funktion: das README beschreibt eine automatische Glossarerzeugung, die Terminologie über ein Dokument hinweg konsistent halten soll.
Die dritte Stufe ist der Rückbau in das Zieldateiformat. Hier liegt der Qualitätsunterschied zwischen den Formaten. Für docx und xlsx verspricht das README Formaterhaltung. Für pdf gibt es diesen Anspruch nicht, weil das Zwischenformat bereits eine andere Struktur hat als das Original.
Installation und Start: die realen Befehle aus dem README
Der schnellste Weg führt über pip. Das README nennt `pip install docutranslate`, danach `docutranslate -i`. Wer die MCP-Erweiterung braucht, installiert `pip install docutranslate[mcp]` und startet `docutranslate -i --with-mcp`. Mit uv lautet die Sequenz `uv init`, `uv add docutranslate`, `uv run --no-dev docutranslate -i`. Aus dem Repository heraus klont man und führt `uv sync --no-dev` aus, mit `--all-extras` für alle optionalen Abhängigkeiten.
Für Container gibt es ein fertiges Image: `docker run -d -p 8010:8010 xunbu/docutranslate:latest`. Der Port 8010 ist der Standard, die Weboberfläche liegt danach unter `http://127.0.0.1:8010`, die Swagger-Dokumentation unter `http://127.0.0.1:8010/docs`. Wer aus dem LAN zugreifen will, startet mit `docutranslate -i --host 0.0.0.0`; ein anderer Port kommt über `-p 8081`.
Die Konfiguration läuft über Umgebungsvariablen. Drei davon sind laut README zwingend: DOCUTRANSLATE_API_KEY, DOCUTRANSLATE_BASE_URL und DOCUTRANSLATE_MODEL_ID. Optional sind DOCUTRANSLATE_TO_LANG (Standard Chinesisch), DOCUTRANSLATE_CONCURRENT (Standard 10), DOCUTRANSLATE_CONVERT_ENGINE und DOCUTRANSLATE_MINERU_TOKEN. Für den PDF-Pfad nennt das README mineru als Engine, entweder online oder lokal betrieben, zuständig für Tabellen, Formeln und Code. Wer diesen Pfad nutzt, braucht den MinerU-Token, sonst bleibt nur der weniger leistungsfähige Weg.
MCP und die Mehrbenutzerfähigkeit als eigentliche Integrationspunkte
Interessanter als die Weboberfläche ist die MCP-Anbindung. DocuTranslate kann als MCP-Server laufen, in drei Transportvarianten: stdio über `docutranslate --mcp`, SSE über `docutranslate --mcp --transport sse` und Streamable HTTP über `--transport streamable-http`. Im SSE-Betrieb lassen sich Host und Port getrennt setzen, etwa `--mcp-host 127.0.0.1 --mcp-port 8000`, der Endpunkt liegt dann unter `http://127.0.0.1:8000/mcp/sse`.
Für die Einbindung ohne lokale Installation zeigt das README eine uvx-Konfiguration, bei der der Server als `uvx --from docutranslate[mcp] docutranslate --mcp` gestartet und über den env-Block mit Key, Basis-URL, Modell, Zielsprache, Nebenläufigkeit und MinerU-Token versorgt wird. Das ist der Punkt, an dem DocuTranslate aufhört, ein Werkzeug mit Fenster zu sein, und zu einer Komponente in einer größeren Kette wird.
Dazu passt die LAN-Fähigkeit. Das README nennt ausdrücklich die gleichzeitige Nutzung durch mehrere Personen im lokalen Netz. Der Start mit `--host 0.0.0.0` öffnet die Oberfläche für andere Geräte. Wer das tut, sollte wissen, dass damit auch die API erreichbar ist, sofern sie nicht anderweitig abgesichert wird. Das README beschreibt dazu keine Authentifizierung.
Die PDF-Grenze ist keine Fußnote, sondern eine Designentscheidung
Das README enthält einen hervorgehobenen Hinweis: bei der Übersetzung von pdf wird die Datei zuerst in Markdown konvertiert, wodurch das ursprüngliche Layout verloren geht. Personen mit strengen Layoutanforderungen werden ausdrücklich zur Vorsicht gemahnt. Das ist ehrlich formuliert und sollte ernst genommen werden.
Die Konsequenz ist konkret. Ein zweispaltiger Aufsatz mit Abbildungen, Randnotizen und Formelsatz wird nach der Konvertierung als linearer Markdown-Text behandelt. Die Übersetzung kann inhaltlich korrekt sein, das Ergebnis ist aber kein layoutgleiches PDF. Wer eine druckfertige zweisprachige Ausgabe braucht, bekommt sie hier nicht. Der Nutzen liegt bei der inhaltlichen Erschließung, nicht bei der Reproduktion.
Dazu kommt eine Abhängigkeit außerhalb des Projekts. Die Erkennung von Tabellen, Formeln und Code im PDF-Pfad läuft laut README über mineru, online oder lokal. Das bedeutet: die Qualität dieses Teils hängt nicht von DocuTranslate ab, sondern von mineru und, im Online-Betrieb, von einem zusätzlichen Token und einer externen Instanz. Wer mineru lokal betreibt, trägt den Betriebsaufwand selbst. Wer es online nutzt, schickt den Dokumentinhalt durch einen weiteren Dienst.
Ein zweiter Grenzfall ist die Dateiendung. Das README nennt docx und xlsx als unterstützt und schließt doc und xls ausdrücklich aus. Wer mit alten Binärformaten arbeitet, muss vorher konvertieren.
Was DocuTranslate nicht ist: Abgrenzung zu Pandoc plus Übersetzungsskript
Die naheliegende Alternative ist eine eigene Kette aus Pandoc für die Formatkonvertierung und einem kurzen Skript für die LLM-Aufrufe. Der Unterschied liegt nicht in der Konvertierungsqualität, sondern in dem, was drumherum schon existiert.
Pandoc deckt die Formatkonvertierung breit ab und ist ein etabliertes Werkzeug. Was es nicht mitbringt, ist alles nach der Konvertierung: Segmentierung in übersetzbare Einheiten, asynchrone Parallelverarbeitung mit einstellbarer Nebenläufigkeit, Glossar-Erzeugung zur Terminologiekonsistenz, ein Web-Interface, eine REST-API und einen MCP-Server. Genau diese Teile müsste man in einem eigenen Skript nachbauen, und genau diese Teile sind der Aufwand.
Umgekehrt hat die Eigenbaulösung einen Vorteil, den DocuTranslate nicht bietet: volle Kontrolle über die Segmentgrenzen. Wer bei juristischen Texten oder bei Codeblöcken sehr genau steuern muss, was als eine Übersetzungseinheit gilt, wird mit einem eigenen Skript präziser arbeiten können. DocuTranslate gibt hier nur die jsonpath-ng-Auswahl für json als expliziten Steuerungsmechanismus an die Hand. Für alle anderen Formate beschreibt das README keine vergleichbare Kontrolle über die Segmentierung.
Die Wahl hängt also davon ab, ob man die Infrastruktur oder die Feinsteuerung braucht. DocuTranslate liefert die Infrastruktur.
Wartung, Release-Takt und was die Lizenz bedeutet
Die Release-Historie zeigt einen kurzen Takt: v1.7.7 im Juni 2026, v1.7.8 im Juli, v1.7.9 im September. Das Repository ist nicht archiviert, der letzte Push fällt mit dem jüngsten Release zusammen. Für ein Werkzeug dieser Art ist das ein Hinweis auf aktive Pflege, mehr aber auch nicht. Ob Fehler schnell geschlossen werden, lässt sich daraus nicht ableiten.
Der Wartungsaufwand für Anwender hängt an zwei externen Größen. Erstens am Modell: DOCUTRANSLATE_BASE_URL und DOCUTRANSLATE_MODEL_ID sind frei wählbar, ein Modellwechsel auf Anbieterseite kann das Übersetzungsverhalten verändern, ohne dass sich am Projekt etwas ändert. Zweitens an mineru: der PDF-Pfad hängt an einer Komponente, die nicht im Repository liegt und im Online-Betrieb einen eigenen Token erfordert.
Die Lizenz ist MPL-2.0. Das ist eine Datei-basierte Copyleft-Lizenz: Änderungen an vorhandenen Dateien des Projekts müssen unter derselben Lizenz offengelegt werden, während eigene Dateien, die mit dem Projekt kombiniert werden, unter anderen Bedingungen stehen können. Für die bloße Nutzung als Werkzeug oder als aufgerufener Dienst entstehen daraus keine Veröffentlichungspflichten für eigene Inhalte. Wer DocuTranslate forkt und die geänderten Dateien weitergibt, muss die Lizenzbedingungen einhalten. Das ist eine allgemeine Einordnung, keine Rechtsberatung; für den eigenen Fall ist der Lizenztext maßgeblich.
Redaktionelles Fazit
Wer docx, xlsx, epub oder srt mit einem eigenen API-Key übersetzen will und bereit ist, die Qualität der Zielsprache selbst zu prüfen, findet hier ein schlankes Werkzeug mit Web-UI, REST-API und MCP-Anbindung. Wer layouttreue PDF-Ausgaben braucht, sollte DocuTranslate nicht als Lösung einplanen: das README sagt ausdrücklich, dass die Konvertierung nach Markdown das Original-Layout verliert. Vor dem ersten produktiven Lauf ist zu klären, welcher DOCUTRANSLATE_CONVERT_ENGINE gesetzt wird und ob DOCUTRANSLATE_MINERU_TOKEN vorhanden ist, denn davon hängt ab, ob Tabellen, Formeln und Code in PDFs überhaupt erkannt werden. Ein zweiter Prüfpunkt ist der API-Key: das Projekt selbst liefert kein Modell, jeder Lauf kostet Token beim gewählten Anbieter.
Community-Notizen