major
#29111
Bei der JavaDoc-basierten I18N-Generierung werden benutzerdefinierte ResKeys in I18NConstants ignoriert
Wenn ein ResKey- Feld in einer I18NConstants-Klasse über ResKey.internalCreate() mit einem benutzerdefinierten Schlüssel vorinitialisiert wird, generiert das TLDoclet den Eintrag „messages_en.properties“ unter dem normativen Schlüssel (class.pkg.ClassName.FIELD_NAME) anstelle des benutzerdefinierten Schlüssels. Zur Laufzeit enthält das Feld den benutzerdefinierten Schlüssel, sodass die lokalisierte Zeichenfolge aus JavaDoc niemals gefunden wird.
Beispiel
{{{#!java /**
- @en Audio abspielen */
public static ResKey JS_AUDIO_PLAYER_PLAY = ResKey.internalCreate("js.audioPlayer.play"); }}}
- TLDoclet generiert: class.com.top_logic.layout.react.I18NConstants.JS_AUDIO_PLAYER_PLAY = Audio abspielen (in META-INF/messages_en.properties)
- Die Laufzeit sucht nach: js.audioPlayer.play (der benutzerdefinierte Schlüssel aus internalCreate)
- Ergebnis: Der englische Text wird unter dem Laufzeit-Schlüssel nie gefunden
Dies zwingt Entwickler dazu, die Übersetzungen manuell in einer separaten Datei unter WEB-INF/conf/resources/*.messages_en.properties zu duplizieren.
Vorgeschlagene Lösung
Fügen Sie eine @CustomKey -Annotation hinzu, die auf ResKey -Felder in I18NConstants- Klassen angewendet werden kann. Sowohl das Doclet als auch der Laufzeit-Initialisierer lesen diese Annotation, um den korrekten Schlüssel abzuleiten.
Vorher (fehlerhafte JavaDoc-Generierung): {{{#!java public static ResKey JS_AUDIO_PLAYER_PLAY = ResKey.internalCreate("js.audioPlayer.play"); }}}
Nachher (JavaDoc-Generierung funktioniert korrekt): {{{#!java @CustomKey("js.audioPlayer.play") public static ResKey JS_AUDIO_PLAYER_PLAY; }}}
Erforderliche Änderungen:
- Neue Annotation @CustomKey in com.top_logic.basic.i18n (@Target(FIELD), @Retention(RUNTIME))
- I18NConstantsBase.initField(): Auf die Annotation @CustomKey prüfen, deren Wert anstelle des normativen Schlüssels verwenden
- TLDoclet.collectI18NConstantDoc(): Auf die Annotation @CustomKey prüfen, deren Wert anstelle des normativen Schlüssels verwenden
- Vorhandene Verwendungen von ` ResKey.internalCreate()` in den I18NConstants-Klassen migrieren
Migration
Aufrufe von `legacyKey()` wurden durch die Annotation `@CustomKey` ersetzt
Alle ResKey-Felder in I18NConstants-Klassen, die bisher legacyKey(), legacyKey1(), legacyKey2() usw. zur Zuweisung eines benutzerdefinierten Ressourcenschlüssels verwendet haben, müssen nun stattdessen die Annotation @CustomKey verwenden.
Vorher: {{{#!java public static ResKey MY_KEY = legacyKey("my.custom.key"); public static ResKey1 MY_KEY_1 = legacyKey1("my.custom.key"); }}}
Nachher: {{{#!java @CustomKey("my.custom.key") public static ResKey MY_KEY;
@CustomKey("my.custom.key") public static ResKey1 MY_KEY_1; }}}
Das Feld darf nicht initialisiert werden – initConstants() übernimmt dies anhand des benutzerdefinierten Schlüssels aus der Annotation. Dasselbe gilt für Felder, die mit ResKey.internalCreate("...") initialisiert werden.
Dadurch wird sichergestellt, dass sowohl die Laufzeit (I18NConstantsBase) als auch das Doclet zur Erstellungszeit (TLDoclet) denselben benutzerdefinierten Schlüssel verwenden, sodass @en-JavaDoc-Übersetzungen korrekt unter dem benutzerdefinierten Schlüssel in die Datei „messages_en.properties“ geschrieben werden.
Migration von WEB-INF-Ressourceneigenschaften in JavaDoc
In com.top_logic.layout.tools.cleanup steht das Migrationswerkzeug „MigrateResourcesToJavaDoc“ zur Verfügung, um englische Übersetzungen automatisch aus den Dateien „WEB-INF/conf/resources/*_en.properties“ in @en-JavaDoc-Tags für die entsprechenden ResKey-Felder zu verschieben. Das Tool berücksichtigt @CustomKey-Annotationen beim Abgleichen von Schlüsseln mit Feldern. Nach der Migration werden die Einträge aus den Eigenschaftsdateien entfernt.