10. Juli 2026 - Dev Journal

Markdown → JSONL‑Converter wurde verwendet, um die offizielle Dokumentation von 1 180 auf 1 230 JSONL‑Einträge zu erweitern.
Die mehrsprachige Übersetzungspipeline verzögert sich stärker als erwartet; es wurde festgestellt, dass die Stabilisierung länger dauern kann.
In einem privaten Repository wurde die Synchronisationspipeline für mehrsprachige Dokumente getestet; dabei gelten die folgenden Kriterien, die ich festgelegt habe.

Kriterien für die Dokumentenstruktur

Das koreanische Dokument dient als Referenzdokument.
Mehrsprachige Dokumente liegen im Format docs/<lang>/….
Unterverzeichnisse, die bisher direkt unter docs/ lagen, werden als koreanische Referenzdokumente 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.
Übersetzungen der README werden ebenfalls relativ zum Root behandelt.
Änderungen an README.md dürfen nicht fälschlicherweise als Änderungen an Dateien innerhalb 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.

Richtlinien für Links und Pfade

README‑ und interne Links in docs werden an die Zielsprache angepasst. Zum Beispiel wird ein Link docs/ko/... in einem koreanischen README in einem englischen README zu docs/en/... geändert.
Relative Pfade, die Dokumente innerhalb von docs verbinden, werden ebenfalls an die Zielsprache angepasst.
Bildpfade, Unterverzeichnis‑Links und relative Pfade dürfen beim Übersetzungs‑/Synchronisationsprozess nicht beschädigt werden.
Die Sprach‑Links im README sollten so gestaltet sein, dass der Benutzer das Gefühl hat, zur jeweiligen Sprachversion des Dokuments zu wechseln.

Automatisches Synchronisationskriterium:

Wenn in docs/ko eine Datei hinzugefügt wird, wird in den anderen Sprachen eine entsprechende Datei erzeugt.
Wenn in docs/ko eine Datei gelöscht wird, wird die entsprechende Datei in den anderen Sprachen ebenfalls gelöscht.
Wenn eine bestimmte Datei in docs/ko geändert wird, wird nur die entsprechende Datei in den anderen Sprachen erneut erzeugt.
Es wird nicht jedes Mal alles von Anfang an übersetzt.
Bereits erfolgreich übersetzte Sprachen/Dateien werden nicht erneut übersetzt.
Auch bei einem Fehlschlag werden die bereits erfolgreichen Ergebnisse nicht gelöscht.
Nur die fehlgeschlagenen Ziel‑Dateien werden entfernt und beim nächsten Durchlauf erneut erzeugt.
Der Vergleich der Dateianzahl oder einfacher Versionsdateien lässt bereits passende Sprachordner überspringen.
Versionsdateien verwenden ein einfaches Format wie v1 oder eine Zahl, anstatt komplexer JSON/Hashes.

Übersetzungs‑Verarbeitungs‑Kriterium:

Die Übersetzung wird mit der echten API getestet.
Mock-Erfolgsbehandlung wird nicht verwendet.
Die Chunk-Größe wird anhand der offiziellen Kontext-/Ausgabelimits des Modells festgelegt.
Es ist wichtiger, die tatsächliche Übersetzungsausgabe so zu kürzen, dass sie max_tokens nicht überschreitet, als den Eingabekontext.
Der Chunk wird sofort nach der Übersetzung geprüft.
Fehlgeschlagene Bereiche nach der Übersetzungsprüfung werden in eine Warteschlange gestellt.
Nur die fehlgeschlagenen Bereiche in der Warteschlange werden mit erhöhter Tiefe weiter aufgeteilt und erneut übersetzt/überprüft.
Eine Struktur, bei der nach dem Zusammenführen aller Chunks nur einmal am Ende geprüft wird, wird vermieden.

Prüfkriterien:

Überprüfen Sie, ob im Übersetzungsergebnis Koreanisch unverändert bleibt.
Überprüfen Sie, ob Leerzeichen entfernt wurden.
Überprüfen Sie, ob die Markdown‑Struktur erhalten bleibt.
Überprüfen Sie, ob Code‑Fences, Links, Bilder und Überschriften erhalten bleiben.
Sprachen, die wie Chinesisch kürzer werden, werden nicht nur anhand der Länge beurteilt.
Lesen Sie das Ergebnis tatsächlich durch und prüfen Sie, ob es im Vergleich zum Original keinen seltsamen Inhalt gibt.

Fehlerprotokoll‑Kriterien:

HTTP 429, 504, RemoteDisconnected, finish_reason=length oder leere Antworten werden als Fehlursachen unterschieden.
Antwort‑Header, Antwort‑Body, Laufzeit, Modellname, Eingabegröße und Token‑Verbrauch werden im Log festgehalten.
Ein einzelner Fehler darf nicht die gesamte Pipeline stoppen oder das Ergebnis verschwinden lassen.
Bei wiederholten Fehlern wird zuerst die Ursache analysiert.

NVIDIA‑API‑Nutzungsrichtlinien:

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

Hard‑Coding‑Richtlinien:

Strukturelle Regeln wie docs/<lang>, Marker, Link‑Regex und Code‑Fence‑Parsing werden verwendet.
Einzelne Wörter werden nicht willkürlich geändert oder entfernt.
example.com wird nicht willkürlich entfernt.
Dokumentdateien werden nicht einzeln über Pfade registriert.
Sprachliche Ausdrücke oder bestimmte Sätze/Wörter werden nicht erzwungen umgeändert.

Betriebsrichtlinien:

Sowohl GitHub Actions als auch Mac‑Self‑Hosted‑Runner werden geprüft.
Auch auf dem Mac soll nach Abschluss ein automatischer Commit/Push erfolgen.
Wie bei GitHub Actions soll der Fortschritt sichtbar sein.
Es soll im Log ersichtlich sein, welche Sprache/Datei/Chunk gerade verarbeitet wird.
Branch‑Name, Run‑URL, Fehlerursache und aktueller Fortschritt werden klar dokumentiert.

Abgesehen von der Übersetzung habe ich kürzlich ein interessantes Dokument gefunden.

Pollinations API‑DOKUMENTATION.md prüfen
Man kann mit curl ohne API‑Schlüssel Textantworten erhalten, und es scheint auch Bildgenerierung zu unterstützen
Vielleicht lässt sich das leicht experimentell nutzen, ohne sich Sorgen um Kosten für einen API‑Schlüssel zu machen
Ich habe bereits etwas Spaßiges damit entwickelt und plane, nach weiterer Nutzung es 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 ausschließlich 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 für das 3 -> 4‑Umwandlungs‑Begründungs‑JSONL sind für Godot‑3‑Code Ja, für Godot‑4‑Code Nein
- Die erwarteten Validierungswerte für das irrelevante Umwandlungs‑JSONL sind für sowohl Godot‑3‑ als auch Godot‑4‑Code Nein
Rückblick: docs/retrospectives/2026-07-10.md