#29111 JavaDoc-based I18N generation ignores custom ResKey in I18NConstants

enhancement

major

#28994

TableComponent: ConfigKey should be customizable

#29055

User-specified CSS classes cannot override default numeric alignment in table columns

#29084

JSON Schema Support for Typed Configuration

#29092

Multi-factor authentication and self-service account management

minor

#29037

Upload/update workflows at application startup

#29095

No fixed reference to tl-build-processor in tl-parent-build

#29204

TreeGrid Modelbuilder API: Node predicate does not get component model

nice-to-have

#29103

Making REST client JSON parser robust against empty content

defect

critical

#29080

Unwanted row objects in tables with changes from other sessions

#29199

XSS vulnerability in /jsp/openapi/server/displayAPISpec.jsp

major

#28674

Security issues in the UMLJS project

#28710

Accounts with reused contact have no authorization

#28993

Filters of dynamic columns ignore the attribute type

#29042

Error in column filter for double values

#29107

StackOverflowError when rolling back in the transaction monitor

#29111

JavaDoc-based I18N generation ignores custom ResKey in I18NConstants

minor

#27850

Modelleditor swallows classification with a less-than sign in the name

#28456

Reference to missing files in subsession.jsp

#28485

Immutable/Disbled Boolean fields accessible/focusable via tab

#28651

Unnecessary space for inline tables

#28725

Pointless scroll bar in the help editor

#29053

TL-Script: format() with null input returns IllegalArgumentException

#29061

Missing replacement of KnowledgeItem by ObjectKey in Collections in Queries

#29066

"SafeHTML not started" error with scripted tests

#29069

A calculated attribute of the type "General search expression" cannot return a closure

#29073

Abstract attributes can be accessed in transient objects

#29074

The form data of a component cannot be accessed in a value transformation of a component channel

#29075

After changing the model, calculated attributes that have become invalid can no longer be edited

#29076

API key in REST interface configuration is not hidden

#29087

Incorrect access to the D&D cache in the browser

#29091

Values of a composition attribute cannot be edited if previously used in the same form

#29106

Error when restarting the KnowledgeBase

#29112

Update minimatch and serialize-javascript to fix CVE-2026-27903, CVE-2026-27904, and GHSA-5c6j-r48x-rmvq

#29197

Eclipse error after dependency update: maven-jar-plugin 3.5.0 causes "outside of a scoping block" error in m2e

update

critical

#29110

Update dependency com.fasterxml.jackson.core:jackson-core to v2.21.1 [SECURITY]

defect

major

#29111

JavaDoc-based I18N generation ignores custom ResKey in I18NConstants

I18N Migration

When a ResKey field in an I18NConstants class is pre-initialized with a custom key via ResKey.internalCreate(), the TLDoclet generates the messages_en.properties entry under the normative key(class.pkg.ClassName.FIELD_NAME) instead of the custom key. At runtime, the field holds the custom key, so the localized string from JavaDoc is never found.

Example

{{{#!java /**

@en Play audio */

public static ResKey JS_AUDIO_PLAYER_PLAY = ResKey.internalCreate("js.audioPlayer.play"); }}}

TLDoclet generates: class.com.top_logic.layout.react.I18NConstants.JS_AUDIO_PLAYER_PLAY = Play audio (in META-INF/messages_en.properties)
Runtime looks up: js.audioPlayer.play (the custom key from internalCreate)
Result: English text is never found under the runtime key

This forces developers to manually duplicate the translations in a separate WEB-INF/conf/resources/*.messages_en.properties file.

Proposed Fix

Add a @CustomKey annotation that can be placed on ResKey fields in I18NConstants classes. Both the doclet and the runtime initializer read this annotation to derive the correct key.

Before (broken JavaDoc generation): {{{#!java public static ResKey JS_AUDIO_PLAYER_PLAY = ResKey.internalCreate("js.audioPlayer.play"); }}}

After (JavaDoc generation works correctly): {{{#!java @CustomKey("js.audioPlayer.play") public static ResKey JS_AUDIO_PLAYER_PLAY; }}}

Changes needed:

New annotation @CustomKey in com.top_logic.basic.i18n(@Target(FIELD), @Retention(RUNTIME))
I18NConstantsBase.initField(): check for @CustomKey annotation, use its value instead of normative key
TLDoclet.collectI18NConstantDoc(): check for @CustomKey annotation, use its value instead of normative key
Migrate existing ResKey.internalCreate() usages to I18NConstants classes

Code migration

legacyKey() calls replaced by @CustomKey annotation

All ResKey fields in I18NConstants classes that used legacyKey(), legacyKey1(), legacyKey2(), etc. to assign a custom resource key must now use the @CustomKey annotation instead.

Before:{{{#!java public static ResKey MY_KEY = legacyKey("my.custom.key"); public static ResKey1 MY_KEY_1 = legacyKey1("my.custom.key"); }}}

After:{{{#!java @CustomKey("my.custom.key") public static ResKey MY_KEY;

@CustomKey("my.custom.key") public static ResKey1 MY_KEY_1; }}}

The field must not be initialized - initConstants() handles it using the custom key from the annotation.

This ensures that both the runtime (I18NConstantsBase) and the build-time doclet (TLDoclet) use the same custom key, so that @en JavaDoc translations are correctly written to messages_en.properties under the custom key.

Migrating WEB-INF resource properties to JavaDoc

A migration tool MigrateResourcesToJavaDoc is available in com.top_logic.layout.tools.cleanup to automatically move English translations from WEB-INF/conf/resources/*_en.properties files into @en JavaDoc tags on the corresponding ResKey fields. The tool respects @CustomKey annotations when matching keys to fields. After migration, the entries are removed from the properties files.