enhancement
major
minor
major
minor
major
#29623
Build: Das „translate“-Ziel übersetzt festgeschriebene deutsche Meldungen nach einem Pull oder einem Wechsel des Zweigs neu, wenn das Doclet nicht im selben Build ausgeführt wurde.
Problem
Die deutschen Ressourcenbündel (src/main/java/META-INF/messages_de.properties) werden manuell gepflegt; der Build soll neue Schlüssel über DeepL generieren und bestehende Einträge, deren englischer Text sich nicht geändert hat, niemals verändern. Manchmal ersetzt ein lokaler Build dennoch bestehende deutsche Einträge durch neue maschinelle Übersetzungen, und zwar in ganzen Modulen auf einmal – manuell überarbeitete Texte wie „Läuft“ für den Status „Running“ werden zu „Laufen“.
Ursache
Das TLDoclet generiert die Datei „messages_en.properties“ neu und behält die vorherige Datei als „messages_en.properties~“ bei. Das „translate “-Ziel des tl-maven-plugin (Ausführung von „translate-system-messages“ im tl-parent-build, Phase „prepare-package“) verwendet diese Tilde-Datei als „referencePath“: Jeder Schlüssel, dessen englischer Text sich zwischen der Referenzdatei und der aktuellen „messages_en.properties“ unterscheidet, wird erneut übersetzt (ResourceTranslator.isKeyToUpdate).
Die Tilde-Datei ist ein nicht nachverfolgtes, arbeitsbaum-spezifisches Artefakt: Sie speichert die englischen Texte so, wie sie beim letzten Ausführen des Doclets //in diesem Arbeitsbaum// waren. Nach einem Pull oder einem Wechsel des Zweigs enthält die festgeschriebene „messages_en.properties“-Datei die englischen Texte der Änderungen anderer Personen, während die Referenzdatei weiterhin den alten Zustand beschreibt. Wenn das Doclet dann nicht vollständig ausgeführt wird – beispielsweise bei einem Build ohne JDK, bei dem das Javadoc-Plugin mit der Fehler meldung „Unable to find javadoc command“ fehlschlägt, aber „failOnError=false“ den Build fortsetzt; oder ein Doclet-Lauf, der aufgrund unlösbarer Abhängigkeiten abgebrochen wird – wird keine der beiden Dateien aktualisiert, das „translate“-Ziel wird dennoch ausgeführt und übersetzt jeden Schlüssel neu, der sich auf dem Zweig seit dem letzten lokalen Doclet-Lauf geändert hat, wobei die deutsche Übersetzung ersetzt wird, die der Autor dieser Änderung bereits festgeschrieben hatte.
Beispiel aus einem Arbeitsverzeichnis, das den Master-Zweig (9d4d5c2d8c → 91ad0edc58) abgerufen und anschließend „rebuild-stale.sh“ ohne JDK ausgeführt hat:
| = Modul = | = Durch den Pull geänderte englische Zeilen = | = von DeepL übersetzte Zeilen = |
| com.top_logic | 16 | 16 |
| com.top_logic.element | 1 | 1 |
| com.top_logic.layout.react | 41 | 41 |
| com.top_logic.layout.view | 190 | 190 |
Ein Build, bei dem das Doclet ausgeführt wird, ist davon nicht betroffen: Das Doclet verschiebt die festgeschriebenen englischen Dateien in den Tilde-Verweis und generiert die englischen Texte neu aus den Quellen, sodass der Verweis dem festgeschriebenen Zustand entspricht und sich nur tatsächlich geänderte Texte unterscheiden.
Lösung
Das „translate“-Ziel wird nur ausgeführt, wenn das Doclet das englische Bundle, das es sieht, im selben Build generiert hat, da nur dann die Tilde-Referenz dem Zustand entspricht, den die englischen Texte hatten, bevor dieser Build sie neu generiert hat.
- TLDoclet markiert einen abgeschlossenen Durchlauf: Nach dem Schreiben von `messages_en.properties ` (und dessen Tilde-Sicherung) schreibt es eine Markerdatei `target/messages-generated.marker ` (Option `-messagesMarker`, eine Eigenschaft `messagesMarker` in `tl-parent-build`), die den SHA-256-Digest des von ihm generierten Bundles enthält. Der Marker ist modul-lokal und wird durch „mvn clean“ entfernt; er ist nicht vom gemeinsam genutzten „javadocOutput“ der Framework-Module abhängig.
- Das „translate“-Ziel nimmt die Marker-Datei als Parameter „generationMarker“ entgegen (konfiguriert neben „referencePath“). Es verarbeitet die Marker-Datei als Erstes – löscht sie, auch wenn die Übersetzung durch „tl.javadoc.skipTranslate“ übersprungen wird –, sodass keine Marker-Datei den Build überdauert, der sie erstellt hat. Ohne Marker wird protokolliert, dass das Doclet nicht ausgeführt wurde, und der Vorgang wird übersprungen. Bei einem Marker, dessen Digest von der aktuellen „messages_en.properties“-Datei abweicht – ein Marker, der von einem Build hinterlassen wurde, der zwischen dem „javadoc“- und dem „translate“-Ziel abgebrochen wurde, gefolgt von einem „pull“ –, wird protokolliert, dass sich das Bundle seit der Erstellung durch das Doclet geändert hat, und der Vorgang wird übersprungen. Nur ein zum Bundle passender Marker lässt die Übersetzung laufen.
- Aufrufe des Ziels ohne den Parameter verhalten sich wie bisher.
Test
- Erstellen Sie ein Modul mit einem JDK: Das Doclet wird ausgeführt, neue Schlüssel werden wie bisher übersetzt, bestehende Einträge mit unverändertem englischen Text bleiben unberührt, der Marker ist nach dem Build verschwunden.
- Ersetzen Sie die Tilde-Referenz eines Moduls durch einen älteren englischen Zustand und erstellen Sie den Build mit -Dmaven.javadoc.skip=true: Der Build protokolliert, dass die Übersetzung übersprungen wird, und messages_de.properties bleibt wie festgeschrieben.
- Erstellen Sie mit -Dtl.javadoc.skipTranslate=true: Der Marker wird dennoch verarbeitet.
- Schreiben Sie einen Marker mit dem Digest des aktuellen Bundles, ersetzen Sie das Bundle durch einen älteren Zustand und führen Sie den Build mit -Dmaven.javadoc.skip=true durch: Der Build protokolliert, dass sich das Bundle seit seiner Erstellung geändert hat, und überspringt die Übersetzung; bleibt das Bundle unverändert, wird die Übersetzung ausgeführt.
- Das tl-maven-Plugin verfügt über keine Infrastruktur für Unit-Tests; die Entscheidung wird durch diese Builds verifiziert.