TransForge: Übersetzen Sie eine statische Website mit einem lokalen LLM – nur die Seiten, die sich geändert haben.

Diese Website ist auf Englisch sowie sieben weiteren Sprachen verfügbar – und ich habe noch nie eine Seite von Hand übersetzt. TransForge übernimmt das: ein Kommandozeilen-Tool, das jede Markdown-Seite an ein Modell auf meinem eigenen GPU-Server sendet, das Ergebnis prüft und anschließend page.ja.md neben page.md schreibt. Entscheidend ist dabei die Verwaltung der Übersetzungen: TransForge speichert einen „Fingerabdruck“ jeder Quellseite sowie jeder von ihm erstellten Übersetzung. Dadurch werden bei nächtlichen Ausführungen nur veränderte Seiten übersetzt – und manuell korrigierte Übersetzungen werden niemals überschrieben.

Was am Ende dabei herauskommt

Ein einziger Befehl zeigt den aktuellen Stand aller Sprachen an. So sieht es auf dieser Website am 19. Oktober 2026 aus (43 englische Seiten, sieben Sprachen):

$ transforge status --site laserlloyd
site laserlloyd: 43 source pages x 7 languages | model mradermacher/Hy-MT2-30B-A3B-i1-GGUF/Hy-MT2-30B-A3B.i1-Q4_K_S
  lang     missing     stale    edited untracked     drift   current
  ja             1         0        10         0         0        32
  zh             1         0         8         0         0        34
  ...
  -> 7 sibling(s) need translation

Der Befehl status kontaktiert den Modellserver nicht, sondern liest lediglich die Website-Daten sowie das Manifest. Mit transforge run --site laserlloyd werden anschließend nur die sieben fehlenden Seiten übersetzt – nichts weiter. In der Spalte „edited“ finden sich Seiten, deren Übersetzung nach der automatischen Erstellung manuell verändert wurde; diese bleiben unberührt, bis ich etwas anderes anordne.

Auch einzelne Textabschnitte lassen sich übersetzen – praktisch für einmalige Tests mit einem Modell:

$ echo "Only the pages that changed get translated again." | transforge text --to ja
変更されたページのみ、再翻訳されます。

Dies dauerte lediglich 15 Sekunden – das Modell war auf dem GPU-Server bereits aktiv.

Wie TransForge entscheidet, was übersetzt wird

Für jede Quellseite und Zielsprache speichert TransForge den Hash des englischen Originaltextes, den Hash der erstellten Übersetzung sowie den Hash der Einstellungen, die die Ausgabe beeinflussen (Modell, Prompt, Schutzwörter, Temperatur). Der Vergleich dieser Werte ergibt für jede Kombination aus Seite und Sprache einen Status:

Status	Bedeutung	Wird mit run übersetzt?
missing	Keine Übersetzungsdatei vorhanden	Ja
stale	Das Original wurde geändert	Ja
edited	Manuell bearbeitet	Nein; nur mit --force und explizitem --files
untracked	Übersetzung existiert, wurde aber nicht von TransForge erstellt	Nein; accept übernimmt sie
drift	Quelle und Übersetzung unverändert, aber Modell/Einstellungen änderten sich	Nein; lediglich Information
current	Alles ist bereits aktuell	Nein

Zwei dieser Zustände sind besonders wichtig: Eine manuelle Bearbeitung hat Vorrang vor Änderungen am Originaltext – so bleibt eine Korrektur auch nach automatischen Ausführungen erhalten. Änderungen am Modell führen nicht zu einer vollständigen Neübersetzung; stattdessen wird „drift“ gemeldet, sodass Sie selbst entscheiden können, welche Seiten erneut übersetzt werden sollen.

Vor dem Schreiben der Übersetzung erfolgt eine Prüfung: Die Anzahl von Überschriften, Codeblöcken, Tabellen, Bildern und Links muss mit dem Original übereinstimmen; die Zielsprache muss im Text enthalten sein (z. B. japanische Zeichen bei einer japanischen Seite); geschützte Markennamen dürfen nicht verändert werden – außerdem muss die Übersetzung eine Mindestlänge aufweisen. Bei Verstößen bleibt die bisherige Übersetzung erhalten. Interne Links werden erst nach der Modellausführung von TransForge angepasst – niemals vom Modell selbst: /projects/foo/ wird zu /ja/projects/foo/, sofern eine japanische Version der Seite existiert. Vor dem Überschreiben einer Datei erstellt TransForge zunächst ein Backup.

Installation und erster Testlauf

uv tool install --python 3.13 git+https://github.com/LaserLloyd/TransForge
mkdir -p ~/.config/transforge
cat > ~/.config/transforge/config.toml <<'EOF'
[defaults]
endpoint = "http://localhost:1234"
model = "publisher/repo/file-stem"

[sites.example]
root = "~/sites/example"
content_dirs = ["content/projects", "content/pages"]
languages = ["ja", "de"]
lang_names = { ja = "Japanese", de = "German" }
link_dirs = ["projects"]
no_translate = ["MyProduct"]
translate_fields = ["title", "excerpt"]
EOF
export TRANSFORGE_LLM_API_KEY=...        # nur nötig, falls der Server eine Schlüssel erfordert
transforge config                         # zeigt das verwendete Konfigurations-Setup an; den Schlüssel zeigt es nicht an
transforge models                         # listet alle verfügbaren Modelle auf; kopieren Sie die vollständige Modell-ID in die Konfiguration
transforge run --site example --dry-run   # simuliert den Übersetzungsvorgang
transforge run --site example --limit 2   # übersetzt zwei Seiten und zeigt sie anschließend an

Der Wert von endpoint ist der Server-Pfad ohne „/v1“; model muss die vollständige Modell-ID sein, wie sie vom Server angegeben wird (StudioForge-IDs sehen z. B. so aus: publisher/repo/file-stem). Unbekannte IDs führen zu einem Fehlercode 5 sowie zu möglichen Alternativen. In no_translate geben Sie Begriffe an, die unverändert bleiben sollen; in translate_fields legen Sie fest, welche Metadaten übersetzt werden – alle anderen bleiben unberührt. Auf Debian/Ubuntu sollten Sie nicht mit dem System-Python pip install . ausführen (wegen PEP 668); stattdessen eignen sich uv tool, pipx oder ein virtuelles Umfeld.

Falls Ihre Website bereits auf andere Weise übersetzt wurde, führen Sie einmalig transforge accept --site example aus – dadurch werden die bestehenden Dateien als „aktuell“ markiert, sodass sie nicht erneut übersetzt werden.

Die Rückgabecodes sind für Skripte und Cron-Jobs gedacht: 0 bedeutet Erfolg bzw. nichts zu tun; 1 zeigt an, dass eine Seite fehlschlug (bei status stehen Arbeiten aus); 2 deutet auf Konfigurationsfehler oder ein abgelehntes API-Key-Angebot hin; 4 bedeutet, dass der Server nicht erreichbar ist; 5 signalisiert, dass das Modell nicht verfügbar ist; 6 zeigt an, dass Benchmarks die GPU blockieren, weshalb Jobs verschoben wurden.

Docker

Im Repository finden Sie zudem eine Compose-Konfiguration, mit der TransForge als Werkzeug gegen Ihr Website-Verzeichnis genutzt werden kann; dabei werden Manifeste in einem Volume gespeichert sowie optional ein Scheduler-Service bereitgestellt:

git clone https://github.com/LaserLloyd/TransForge.git && cd TransForge
cp deploy/compose/.env.example deploy/compose/.env    # setzen Sie LLM_BASE_URL und TRANSFORGE_LLM_API_KEY
docker compose -f deploy/compose/compose.yml run --rm app status --all

Dabei werden keine Ports geöffnet. Innerhalb des Containers bezeichnet „localhost“ den Container selbst – das Modell muss also auf einer Adresse lauschen, die vom Container erreichbar ist. Ich nutze TransForge direkt auf meinem System; die Docker-Option habe ich bisher nicht ausprobiert. Details dazu sowie Informationen zu Backups finden Sie in docs/deploy/docker.md.

Neuerungen in Version 0.2.0

Die Veröffentlichung von 0.2.0 im Oktober 2026 konzentriert sich vor allem auf die Nutzung mit einem StudioForge 2.0-Server, der nun einen API-Schlüssel erfordert:

• API-Schlüssel-Unterstützung: TransForge sendet bei jeder Anfrage Authorization: Bearer. Der Schlüssel wird aus TRANSFORGE_LLM_API_KEY (oder STUDIOFORGE_API_KEY, bzw. einer Variablen, die Sie via api_key_env festlegen) gelesen; ein Wechsel des Schlüssels markiert keine Seiten als veraltet. Ohne gültigen Schlüssel erhält man bei einem Server, der ihn verlangt, lediglich eine kurze Fehlermeldung sowie den Code 2.
• Sicherer Umgang mit Benchmarks: Vor der Übersetzung prüft TransForge, ob Benchmarks die GPU belegen – falls ja, wird darauf verzichtet. Früher führte ein fehlerhaftes Ergebnis dieser Prüfung dazu, dass der Schutz deaktiviert wurde; nun erfolgt stattdessen ein Abbruch mit Code 2.
• Windows-Unterstützung: TransForge funktioniert nun auch unter Windows; in Manifesten wird unabhängig vom Betriebssystem „/“ verwendet – so sind sie plattformübergreifend nutzbar. Ältere Windows-Manifeste werden automatisch umgeschlüsselt. Ein Aufruf von accept --all zum „Neuerstellen“ aller Übersetzungen ist zu unterlassen: dadurch würden als aktuell markierte Übersetzungen fälschlicherweise als veraltet gewertet.
• Veralteter PIN-Code: Die Verwaltung von Modell-Ladevorgängen erfolgt nun über den API-Schlüssel; der bisher genutzte PIN-Code bleibt noch in dieser Version funktionsfähig, gibt aber eine Warnung aus, falls er allein verwendet wird.

rig returned HTTP 401 Unauthorized for http://<server>:1234/api/status -- StudioForge requires credentials: set $TRANSFORGE_LLM_API_KEY (or `api_key_env` / `api_key` in the config)

Zur Aktualisierung genügt uv tool install --reinstall --python 3.13 git+https://github.com/LaserLloyd/TransForge; anschließend sollten Sie bei Bedarf TRANSFORGE_LLM_API_KEY setzen.

Hinweise und Fallstricke

• Prüfen Sie die ersten Übersetzungen selbst: Die Überprüfungen stellen lediglich die strukturelle Integrität sicher – nicht aber die sprachliche Korrektheit. Ich nutze dafür ein spezielles Übersetzungsmodell (Hy-MT2 30B) mit dem Prompt-Template „hunyuan-mt“; allgemeine Instruct-Modelle funktionieren ebenfalls, jedoch mit dem Standard-Prompt. Für wichtige Inhalte ist eine menschliche Kontrolle unerlässlich.
• Manuell bearbeitete Übersetzungen bleiben fixiert: Das ist gewollt – bedeutet aber auch, dass nach einer Änderung am Originaltext keine automatische Aktualisierung erfolgt. Mit status -v lassen sich solche Seiten auflisten; mit run --force --files <page> können Sie sie gezielt neu übersetzen.
• Modellwechsel führt nicht zu Neübersetzungen: Stattdessen wird „drift“ gemeldet – Sie müssen dann manuell entscheiden, welche Seiten erneut bearbeitet werden sollen.
• Ausgelegt für StudioForge: Die Initialisierung des Modells sowie die Benchmark-Prüfung nutzen spezifische API-Funktionen von StudioForge. Im README wird zwar erwähnt, dass auch ein llama.cpp-Server zur Übersetzung geeignet ist – ich habe es bisher nur mit StudioForge getestet.
• Keine rekursive Durchsuchung: In content_dirs werden lediglich Verzeichnisse auf der ersten Ebene erfasst; Sie müssen jeden Ordner, der Seiten enthält, separat angeben.
• Englische Seiten bleiben englisch: Legen Sie in den Metadaten en_only: true (oder translate: false) fest – solche Seiten werden komplett ignoriert.

Weitere Informationen

github.com/LaserLloyd/TransForge steht unter MIT-Lizenz zur Verfügung. Im README finden Sie Installationsanleitungen für Windows, Linux und macOS, die vollständige Konfigurationsreferenz sowie eine optionale Überprüfungsstufe, bei der ein externes Modell genutzt werden kann (standardmäßig deaktiviert; die eigentliche Übersetzung erfolgt stets lokal).

Verwandte Themen: StudioForge (der GPU-Server, auf dem das Modell läuft), Verwaltung meiner Websites mittels eines lokalen KI-Agenten sowie Wie man ein Modell dazu bringt, Projekte an das eigene System anzupassen.