10. Juli 2026 | idea_world

Mit dem Markdown → JSONL Converter wurde die offizielle Dokumentations‑JSONL‑Umwandlung von 1 180 auf 1 230 Einträge erhöht.
Die mehrsprachige Übersetzungspipeline verzögert sich stärker als erwartet; es kann also länger dauern, bis sie stabil läuft.
In einem privaten Repository habe ich die Synchronisationspipeline für mehrsprachige Dokumente getestet und dabei folgende Kriterien festgelegt.

Kriterien für die Dokumentenstruktur

Koreanische Dokumente gelten als Ausgangsdokumente.
Dokumente anderer Sprachen liegen im Format docs/<lang>/….
Unterverzeichnisse, die bisher direkt unter docs/ lagen, werden als koreanische Basisdokumente betrachtet und nach docs/ko/… verschoben.
Sprachcodes sind keine willkürlichen Kürzel wie jp oder ch, sondern standardisierte Codes wie ja, zh, pt-BR.
Die README.md im Root bleibt das Root‑Dokument.
Übersetzte README‑Versionen werden ebenfalls im Root behandelt.
Änderungen an README.md dürfen nicht fälschlicherweise als Änderungen innerhalb von docs/ interpretiert werden.
Bereits vorhandene Sprachordner wie docs/en, docs/ja dürfen nicht zu verschachtelten Pfaden wie docs/ko/en führen.
Beim Testen von komprimierten Archiven werden nur README und docs entpackt und übernommen.

Kriterien für Links und Pfade

Links in README und in den Docs werden an die jeweilige Zielsprache angepasst. Beispiel: Ein Link docs/ko/... in der koreanischen README wird in der englischen README zu docs/en/....
Relative Pfade zwischen Dokumenten innerhalb von docs werden ebenfalls an die Zielsprache angepasst.
Bildpfade, Unterverzeichnis‑Links und relative Pfade dürfen beim Übersetz‑/Synchronisationsprozess nicht kaputtgehen.
Die Sprachlinks im README sollen so gestaltet sein, dass der Nutzer das Gefühl hat, zur jeweiligen Sprachversion zu wechseln.

Kriterien für die automatische Synchronisation

Wird eine Datei in docs/ko hinzugefügt, erzeugt die Pipeline entsprechende Dateien in den anderen Sprachen.
Wird eine Datei in docs/ko gelöscht, wird die entsprechende Datei in den anderen Sprachen ebenfalls entfernt.
Wird eine bestimmte Datei in docs/ko geändert, wird nur die entsprechende Datei in den anderen Sprachen neu erzeugt.
Es wird nicht jedes Mal alles von Grund auf neu übersetzt.
Erfolgreich übersetzte Sprachen/Dateien werden nicht erneut übersetzt.
Bei einem Fehlschlag werden bereits erfolgreiche Ergebnisse nicht gelöscht.
Nur die fehlgeschlagenen Ziel‑Dateien werden entfernt und beim nächsten Durchlauf neu erzeugt.
Wenn die Dateianzahl oder eine einfache Versionsdatei bereits stimmt, wird der entsprechende Sprachordner übersprungen.
Versionsdateien verwenden ein einfaches Format wie v1 oder eine Zahl statt komplexer JSON/Hash‑Strukturen.

Kriterien für die Übersetzungs‑Verarbeitung

Die Übersetzung wird mit einer echten API getestet.
Mock‑Erfolge werden nicht verwendet.
Die Chunk‑Größe wird anhand der offiziellen Kontext‑/Ausgabebegrenzungen des Modells festgelegt.
Es ist wichtiger, die Ausgabe so zu kürzen, dass sie max_tokens nicht überschreitet, als den Eingabekontext zu reduzieren.
Direkt nach dem Übersetzen eines Chunks wird dieser sofort geprüft.
Fehlgeschlagene Bereiche werden in eine Warteschlange gestellt.
Nur die in der Warteschlange befindlichen fehlerhaften Bereiche erhalten ein erhöhtes depth, werden feiner aufgeteilt und erneut übersetzt bzw. geprüft.
Ein Ansatz, bei dem alle Chunks erst am Ende zusammengeführt und dann einmalig geprüft werden, wird vermieden.

Prüfungskriterien:

Überprüfen, ob koreanischer Text im Übersetzungsergebnis unverändert bleibt.
Sicherstellen, dass keine Leerzeichen verloren gehen.
Die Markdown‑Struktur muss erhalten bleiben.
Code‑Fences, Links, Bilder und Überschriften dürfen nicht verändert werden.
Bei Sprachen, die wie Chinesisch kürzer werden, darf nicht nur die Länge verglichen werden.
Das Ergebnis muss tatsächlich lesbar sein und keine merkwürdigen Abweichungen vom Original aufweisen.

Fehlerprotokoll‑Kriterien:

Unterscheiden Sie Fehlertypen wie HTTP 429, 504, RemoteDisconnected, finish_reason=length oder leere Antworten.
Protokollieren Sie Antwort‑Header, -Body, Laufzeit, Modellname, Eingabegröße und Token‑Verbrauch.
Verhindern Sie, dass ein einzelner Fehler die gesamte Pipeline stoppt oder das Ergebnis verloren geht.
Bei wiederholten Fehlern zuerst die Ursache analysieren.

NVIDIA‑API‑Nutzungsrichtlinien:

Die Übersetzungspipeline wird anhand der NVIDIA‑API getestet.
gpt-oss-120b unterstützt Eingabekontexte bis zu 128 k, aber die Ausgabe ist laut NVIDIA‑Richtlinie auf etwa 4096 Token begrenzt.
Auch wenn große Eingaben möglich sind, kann das Ergebnis wegen des Ausgabelimits abgeschnitten werden; daher wird das Chunk‑Limit auf 4096 Token festgelegt.
Es werden maximal 40 Aufrufe pro Minute versucht; bei Fehlern gelten Warte‑/Retry‑Strategien.

Hard‑Coding‑Richtlinien:

Verwenden Sie Strukturen wie docs/<lang>, Marker, Link‑Regexes und Code‑Fence‑Parsing.
Ändern oder entfernen Sie keine spezifischen Wörter oder Phrasen willkürlich.
Entfernen Sie nicht example.com.
Registrieren Sie Dokumentdateien nicht einzeln über Pfade.
Vermeiden Sie erzwungene sprachliche Ersetzungen oder Manipulationen einzelner Sätze/Wörter.

Betriebsrichtlinien:

Sowohl GitHub Actions als auch ein selbstgehosteter Mac‑Runner werden geprüft.
Auf dem Mac soll nach Abschluss automatisch ein Commit/Push erfolgen.
Wie bei GitHub Actions soll der Fortschritt sichtbar sein.
Log‑Ausgaben müssen zeigen, welche Sprache/Datei/Chunk gerade verarbeitet wird.
Branch‑Name, Run‑URL, Fehlerursache und aktueller Fortschritt müssen klar dokumentiert werden.

Neben der Übersetzung:

Ich habe kürzlich ein interessantes Dokument entdeckt.
Pollinations APIDOCS.md prüfen
Mit curl lässt sich die API sogar ohne Schlüssel anrufen und erhält Text‑Antworten; Bildgenerierung scheint ebenfalls möglich
Vielleicht lässt sich das leicht experimentell nutzen, ohne sich um Kosten zu sorgen
Ich habe bereits ein kleines Projekt damit gebaut und plane, nach weiterer Nutzung das Ergebnis später zu veröffentlichen
Die Versions‑Trennungs‑JSONL‑Slot‑Struktur des Qwen Validation Debugger wurde neu organisiert
- docs_chunks dient als Begründung für Code‑Erklärungen, daher werden separate Beschreibungs‑/Irrelevanz‑Slots für Godot 3‑Code und Godot 4‑Code beibehalten
- api_mapping und label_prototypes werden nicht in separate JSONL‑Dateien für Godot 3 bzw. Godot 4 aufgeteilt, sondern gemeinsam mit Godot 3‑ und Godot 4‑Code in ein 3 -> 4‑Umwandlungs‑Begründungs‑JSONL eingefügt
- Die erwarteten Validierungswerte des 3 -> 4‑Umwandlungs‑Begründungs‑JSONL sind für Godot 3‑Code Ja, für Godot 4‑Code Nein
- Für das irrelevante Umwandlungs‑JSONL werden die Validierungswerte sowohl für Godot 3‑Code als auch für Godot 4‑Code auf Nein gesetzt
Rückblick: docs/retrospectives/2026-07-10.md