LibreTranslate mit Docker: Übersetzungs-API selbst hosten

Wer Angebote, Support-Tickets oder interne Dokumente maschinell übersetzen lässt, schickt die Texte bei Cloud-Diensten zwangsläufig an einen fremden Server. LibreTranslate ist eine quelloffene Übersetzungs-API, die komplett auf eigener Hardware läuft und dafür die Open-Source-Bibliothek Argos Translate nutzt. Diese Anleitung zeigt Betrieb mit Docker Compose, Schlüsselpflicht, Persistenz sowie Backup und Restore. Alle Messwerte stammen aus einem Testlauf am 01.10.2026 mit Version v1.9.6.

Voraussetzungen

LibreTranslate rechnet standardmäßig auf der CPU, eine Grafikkarte ist nicht nötig. Das optionale CUDA-Image ist rund 1,9 GB groß und nur für amd64 verfügbar. Für ein Sprachpaar wie Deutsch und Englisch reicht ein kleiner Server:

• CPU: 2 Kerne genügen für einzelne Anfragen. Der Testhost hatte 2 Kerne, eine kurze Übersetzung mit zwei Sätzen dauerte dort zwischen 0,18 und 0,34 Sekunden.
• RAM: 2 GB sind das Minimum, 4 GB geben Luft für mehrere Worker und weitere Sprachen. Gemessen wurden 251 MiB im Leerlauf und bis zu 863 MiB nach Text- und Dateiübersetzungen.
• Speicher: etwa 850 MB für das entpackte Image (201 MB Download) plus rund 160 MB je Übersetzungsrichtung. Jede zusätzliche Sprache vergrößert das Modell-Volume deutlich.
• Architektur: Das Image v1.9.6 gibt es laut Docker Hub für amd64 und arm64.
• Software: Docker Engine mit Compose-Plugin, ein Benutzer mit Docker-Rechten, für den Produktivbetrieb ein Reverse Proxy mit TLS.

Schritt 1: Projektstand prüfen und Version festlegen

LibreTranslate wird auf GitHub unter LibreTranslate/LibreTranslate entwickelt und steht unter der AGPL-3.0. Laut GitHub-API hatte das Repository am 01.10.2026 genau 16.961 Sterne, der letzte Push stammt vom 28.09.2026. Das jüngste Release ist allerdings v1.9.6 vom 26.05.2026: Der Code wird aktiv gepflegt, versionierte Releases erscheinen aber in größeren Abständen. Auf Docker Hub gibt es neben den Versionstags auch latest, das zuletzt am 28.09.2026 neu gebaut wurde und damit nicht dem Release-Stand entspricht.

Für einen nachvollziehbaren Betrieb schreiben Sie deshalb eine Version fest. Diese Anleitung nutzt v1.9.6.

Eckdatum	Wert
Image	libretranslate/libretranslate:v1.9.6
Port im Container	5000 (HTTP, Gunicorn)
Volume Modelle	/home/libretranslate/.local
Volume Schlüssel	/app/db mit api_keys.db (SQLite)
Wichtige Variablen	LT_LOAD_ONLY, LT_API_KEYS, LT_REQ_LIMIT, LT_CHAR_LIMIT
Benutzer im Container	UID 1032, GID 65534

Verifizieren: curl -sI https://github.com/LibreTranslate/LibreTranslate/releases/latest leitet auf /releases/tag/v1.9.6 weiter. Weicht der Tag ab, prüfen Sie die Release-Notes, bevor Sie die Version in der .env anpassen.

Schritt 2: compose.yaml und .env anlegen

Legen Sie einen Projektordner an, zum Beispiel /opt/libretranslate. Die Repository-Vorlage enthält Volumes und Schlüssel nur auskommentiert; diese Fassung aktiviert beides und bindet den Port an localhost.

services:
  libretranslate:
    image: libretranslate/libretranslate:${LT_VERSION}
    container_name: libretranslate
    restart: unless-stopped
    ports:
      # nur lokal erreichbar, der Reverse Proxy spricht diesen Port an
      - "127.0.0.1:${LT_HOST_PORT}:5000"
    env_file: .env
    healthcheck:
      test: ['CMD-SHELL', './venv/bin/python scripts/healthcheck.py']
      interval: 10s
      timeout: 4s
      retries: 4
      start_period: 120s
    volumes:
      # Sprachmodelle, verhindert erneuten Download bei jedem Start
      - lt_models:/home/libretranslate/.local:rw
      # SQLite-Datenbank mit den API-Schlüsseln
      - lt_db:/app/db

volumes:
  lt_models:
  lt_db:

Die Variablen stammen aus der offiziellen Argumentliste: Jeder Startparameter hat eine Entsprechung mit Präfix LT_ in Großbuchstaben, aus --char-limit wird also LT_CHAR_LIMIT.

# Version festschreiben, nicht latest
LT_VERSION=v1.9.6
LT_HOST_PORT=18750
# nur Deutsch und Englisch laden
LT_LOAD_ONLY=en,de
# Schlüsseldatenbank aktivieren und Pfad im Volume festlegen
LT_API_KEYS=true
LT_API_KEYS_DB_PATH=/app/db/api_keys.db
# 0 Anfragen pro Minute ohne Schlüssel: Schlüssel wird Pflicht
LT_REQ_LIMIT=0
# maximale Zeichen pro Anfrage
LT_CHAR_LIMIT=5000
# optional, wenn nur die API gebraucht wird
# LT_DISABLE_WEB_UI=true

Die .env enthält keine Geheimnisse, die Schlüssel selbst liegen später in der Datenbank. Die Kombination aus LT_REQ_LIMIT=0 und LT_API_KEYS=true empfiehlt die Dokumentation ausdrücklich, um die API nur noch mit gültigem Schlüssel nutzbar zu machen.

Verifizieren: docker compose config zeigt die aufgelöste Datei mit v1.9.6 und 127.0.0.1:18750 ohne Fehlermeldung.

Schritt 3: Container starten und Modelle laden

cd /opt/libretranslate
docker compose pull
docker compose up -d
docker compose logs -f --no-log-prefix

Beim ersten Start lädt der Container die Modellliste, behält wegen LT_LOAD_ONLY nur zwei der 100 gefundenen Modelle und lädt English → German (1.3) und German → English (1.3) herunter. Im Test stand die Meldung Loaded support for 2 languages (2 models total)! nach rund 15 Sekunden im Log, danach startete Gunicorn auf Port 5000. Das Modell-Volume belegte anschließend 316 MB.

Verifizieren: docker compose ps zeigt healthy, und curl -s http://127.0.0.1:18750/languages liefert genau zwei Einträge, en und de.

Schritt 4: API-Schlüssel anlegen und Pflicht prüfen

Schlüssel verwalten Sie mit dem Werkzeug ltmanage im Container. Die Zahl gibt die erlaubten Anfragen pro Minute an, --char-limit optional eine eigene Zeichengrenze je Schlüssel. Geben Sie den Datenbankpfad immer mit an, damit Werkzeug und Dienst dieselbe Datei verwenden.

# Schlüssel mit 60 Anfragen pro Minute anlegen
docker compose exec libretranslate ./venv/bin/ltmanage keys \
  --api-keys-db-path /app/db/api_keys.db add 60 --char-limit 5000
# vorhandene Schlüssel anzeigen
docker compose exec libretranslate ./venv/bin/ltmanage keys \
  --api-keys-db-path /app/db/api_keys.db

Der Befehl gibt eine UUID aus, das ist der Schlüssel. Geben Sie jedem Werkzeug einen eigenen Schlüssel, dann sperren Sie ihn gezielt mit remove <schlüssel>.

Der Negativtest gehört dazu: Ohne Schlüssel und mit einem erfundenen Schlüssel antwortete die API im Test jeweils mit HTTP 429 und {"error":"Slowdown: 0 per 1 minute"}. Skripte, die nur auf 401 prüfen, erkennen einen falschen Schlüssel deshalb nicht.

Verifizieren: Eine Anfrage ohne api_key liefert 429, dieselbe Anfrage mit gültigem Schlüssel liefert 200.

Schritt 5: Texte und Dateien übersetzen

Die API nimmt JSON oder Formulardaten entgegen. Für eine Übersetzung von Deutsch nach Englisch genügt ein POST auf /translate:

curl -s -X POST http://127.0.0.1:18750/translate \
  -H 'Content-Type: application/json' \
  -d '{"q":"Die Rechnung ist bis Ende des Monats zu bezahlen. Bitte senden Sie uns die unterschriebene Vereinbarung zurück.","source":"de","target":"en","api_key":"IHR-SCHLÜSSEL"}'

Ergebnis im Test: The bill must be paid by the end of the month. Please return the signed agreement to us. Mit "source":"auto" erkennt LibreTranslate die Ausgangssprache selbst und meldet sie mit einer Konfidenz zurück, im Test 43 für einen kurzen deutschen Satz. HTML bleibt mit "format":"html" erhalten. Dateien nimmt der Endpunkt /translate_file als Multipart-Upload an und gibt eine Download-URL zurück. Für Python, PHP, Go und weitere Sprachen nennt die Dokumentation fertige Client-Bibliotheken.

Sprachen, die nicht geladen sind, lehnt der Dienst sauber ab: Eine Anfrage nach Französisch ergab HTTP 400 mit fr is not supported. 6.000 Zeichen scheiterten mit exceeds text limit (5000).

Verifizieren: Die Antwort enthält das Feld translatedText, und docker stats --no-stream libretranslate zeigt die RAM-Belegung unter Last. Im Test waren es rund 860 MiB.

Schritt 6: Persistenz der Modelle prüfen

Ohne Modell-Volume lädt LibreTranslate bei jedem neu erstellten Container alle Modelle erneut herunter. Prüfen Sie deshalb einmal bewusst den kompletten Neuaufbau:

docker compose down
docker compose up -d
docker compose logs --no-log-prefix | grep -E 'Download|Loaded'

Im Test erschien nach dem Neuaufbau keine einzige Downloading-Zeile mehr, der Container war nach rund sechs Sekunden healthy, und der zuvor angelegte Schlüssel funktionierte weiter.

Verifizieren: Die Log-Abfrage liefert keine Download-Zeilen, und eine Übersetzung mit dem alten Schlüssel ergibt HTTP 200.

Schritt 7: Reverse Proxy und TLS

Der Container spricht nur HTTP und lauscht hier auf localhost. Für den Zugriff aus dem Netz setzen Sie einen Reverse Proxy mit automatischem Zertifikat davor, etwa Caddy oder Traefik, und leiten eine Subdomain auf 127.0.0.1:18750 weiter. Geben Sie den Dienst möglichst nur intern oder per VPN frei. Nutzen Sie nur die API, schalten Sie die Weboberfläche mit LT_DISABLE_WEB_UI=true ab; im Test lieferte die Startseite sonst HTTP 200.

Verifizieren: curl -I https://translate.example.de/languages liefert HTTP 200 mit gültigem Zertifikat, und von außen ist Port 18750 nicht erreichbar.

Schritt 8: Backup und Restore der Schlüsseldatenbank

Die Modelle lassen sich jederzeit neu laden, die Schlüsseldatenbank nicht. Sichern Sie daher das Volume lt_db, idealerweise bei gestopptem Container, damit SQLite nicht mitten im Schreiben kopiert wird. Compose stellt den Projektnamen voran, hier libretranslate_lt_db.

mkdir -p backup
docker compose stop
docker run --rm -v libretranslate_lt_db:/data:ro -v "$PWD/backup":/backup \
  alpine tar czf /backup/lt_db.tar.gz -C /data .
docker compose start

Für den Restore stoppen Sie den Dienst, ersetzen die Datei und starten neu. Das Archiv bewahrt die Eigentümer UID 1032 und GID 65534, der Dienst kann die Datei danach wieder schreiben.

docker compose stop
docker run --rm -v libretranslate_lt_db:/data -v "$PWD/backup":/backup:ro \
  alpine sh -c 'rm -f /data/api_keys.db && tar xzf /backup/lt_db.tar.gz -C /data'
docker compose start

Im Test wurde der Schlüssel nach der Sicherung mit ltmanage keys remove gelöscht. Die Liste meldete danach There are no API keys, und Anfragen mit dem Schlüssel scheiterten mit 429. Nach dem Restore war der Schlüssel samt Limit 60 wieder gelistet, die Übersetzung lieferte erneut HTTP 200.

Verifizieren: ltmanage keys listet den gesicherten Schlüssel wieder, und eine Übersetzung damit ergibt HTTP 200.

Schritt 9: Updates und Rollback

Für ein Update tragen Sie den neuen Tag in die .env ein, sichern vorher lt_db und führen docker compose pull sowie docker compose up -d aus. Neue Modellversionen holt LT_UPDATE_MODELS=true beim Start; sie lädt laut Dokumentation immer neu, daher nur für den Update-Lauf setzen. Ein Rollback bedeutet, den alten Tag zurückzuschreiben und neu zu starten. Ob ältere Versionen eine neuere Schlüsseldatenbank lesen, ist nicht dokumentiert; spielen Sie daher auch die Sicherung zurück.

Verifizieren: Die erste Logzeile nach dem Banner zeigt die neue Versionsnummer, docker compose ps meldet healthy.

Schritt 10: LibreTranslate entfernen

Zum vollständigen Entfernen dient docker compose down -v. Achtung: Die Option -v löscht beide Volumes und damit unwiderruflich alle API-Schlüssel. Sichern Sie vorher das Volume lt_db, falls Sie die Schlüssel noch brauchen. Das Image entfernen Sie anschließend mit docker rmi libretranslate/libretranslate:v1.9.6.

Verifizieren: docker volume ls --filter name=libretranslate liefert keine Einträge mehr, und docker ps -a zeigt keinen Container libretranslate.

Troubleshooting

• HTTP 429 trotz Schlüssel: Schlüssel falsch kopiert, gesperrt oder in einer anderen Datenbank angelegt. Prüfen Sie mit ltmanage keys --api-keys-db-path /app/db/api_keys.db, ob er gelistet ist. Ohne Volume auf /app/db gehen Schlüssel beim Neuaufbau verloren.
• Container-Name belegt: Ein zweiter Stack mit derselben Datei scheiterte im Test mit Conflict. The container name "/libretranslate" is already in use. Entfernen Sie container_name oder vergeben Sie einen eindeutigen Namen.
• Sprache fehlt: xx is not supported bedeutet, dass das Modell nicht geladen ist. Ein ungültiger Code in LT_LOAD_ONLY führte im Test zu keiner Fehlermeldung, der Dienst startete normal; kontrollieren Sie nach jeder Änderung /languages.
• Text zu lang: exceeds text limit zeigt die Zeichengrenze. Teilen Sie lange Dokumente auf oder erhöhen Sie das Limit gezielt pro Schlüssel.

Häufige Fragen

Wie gut ist die Übersetzungsqualität?

Für einfache Geschäftssätze ordentlich, für Marketingtexte oder Verträge ohne Nachbearbeitung zu ungenau. Im Test wurde aus „Guten Tag“ brauchbar „Good afternoon“, aus „Guten Morgen“ in einem HTML-Absatz aber „Goodies morning“. DeepL oder große Sprachmodelle liefern meist flüssigere Texte, auf Kosten von Datenweitergabe oder Hardware.

Werden Texte an externe Server gesendet?

Nein, die Übersetzung läuft lokal. Nur beim ersten Start lädt der Container Modellindex und Modelle aus dem Internet.

Wie viele Sprachen sollte ich laden?

Nur die benötigten. Jede Sprache erhöht Speicher, Startzeit und RAM; meist reichen Deutsch und Englisch.

Darf ich LibreTranslate im Unternehmen einsetzen?

Ja, die Software steht unter der AGPL-3.0. Bieten Sie eine veränderte Version als Netzdienst für Dritte an, müssen Sie deren Quellcode bereitstellen. Für den Namen und das Logo gelten zusätzlich die Markenrichtlinien des Projekts.

Fazit

LibreTranslate ist eine schlanke Möglichkeit, Übersetzungen im eigenen Netz zu halten. Mit zwei Sprachen genügt ein kleiner Server, und das Backup beschränkt sich auf eine SQLite-Datei. Die Grenzen liegen bei der Qualität und bei der Rückmeldung der API: Ein falscher Schlüssel ergibt 429 statt 401, und ungültige Sprachcodes fallen erst bei /languages auf. Für Rohübersetzungen, interne Dokumente und die Anbindung eigener Werkzeuge ist LibreTranslate eine gute Wahl, für veröffentlichte Texte bleibt menschliches Gegenlesen Pflicht.

Testumfang

Praktisch getestet wurden mit v1.9.6 auf einem Host mit 2 Kernen der Start mit Healthcheck, Übersetzungen per JSON, Formular, HTML und Datei, Schlüsselpflicht samt Negativtests, Sprach- und Zeichengrenzen, Modellpersistenz nach Neuaufbau, Backup und Restore der Schlüsseldatenbank sowie ein Namenskonflikt als Fehlerbild. Reverse Proxy mit TLS, Updates mit Rollback, das CUDA-Image und der Betrieb auf arm64 stammen nur aus der Dokumentation.

Weiterführende Anleitungen und Quellen

• Caddy als Reverse Proxy mit automatischem HTTPS
• Traefik als Docker-Reverse-Proxy mit HTTPS einrichten
• Ollama und Open WebUI: lokales Sprachmodell als Alternative für anspruchsvollere Texte
• Paperless-ngx: Dokumentenverwaltung mit OCR im eigenen Netz
• LibreTranslate auf GitHub
• Offizielle Dokumentation: Installation und Argumente
• Offizielle Dokumentation: API-Nutzung
• Offizielle Dokumentation: API-Schlüssel verwalten
• Image-Tags auf Docker Hub
• Argos Translate, die zugrunde liegende Übersetzungsbibliothek