Explain parameter usage

[koppor]

The documentation does not bring clarity how to use parameterized messages

Example:

Added\ group\ "%0".=Added group "%0".

Then, i18n.get(Msg.ADDED_GROUP_0, theGroupName) can be used to generate the localized message.

If it it not implemented yet, I would voite for using {} as place holder.

Note: We use the full (!) English message as key to ensure that the Java code is clear w.r.t. concrete message. Maybe, we could change that, but we were successful since approximately 10 years with that. [Details]

[hupfdule]

The usage of parametrized messages is not explicitly mentioned in the documentation as Kilt has no explicit support for them. It is just agnostic to the actual localized messages and whether they contain any placeholders (as is the same with Javas handling of l10n resource bundles).

While it does seem tempting to provide such functionality for ease of use I am not very keen on supporting it. As you already noted, a decision would have to be made about the format of such placeholders (like {}, {0}, %0, :PARAM_NAME:, …) so we had to force the user to this format. ¹
Also we would have to worry about escaping in case such a literal string is used in the message. ²

As is stands now Kilt just returns the bare massage including all placeholders. That can then be filled with the actual parameters. For example by using java.text.MessageFormat:

final String msgTemplate= i18n.get(Msg.ADDED_GROUP_0);
final String msg        = java.text.MessageFormat.format(msgTemplate, theGroupName);

MessageFormat already provides some very sophisticated constructs for applying the correct singular/plural forms, which of course can make the messages rather complicated and hard to read.

While I have no experience with it, com.ibm.icu.text.MessageFormat from ICU4j can likely be used as well.

Or, as jabRef seems to be doing, by using simple String replacements.

Do you still think that Kilt should have explicit support for parametrized messages? If yes, can you provide me examples of the advantages compared to using the above mentioned replacement methods?

Footnotes

1. In fact, I consider {} to be not appropriate for localized messages. While it is certainly easier and less error-prone to type, it restricts the order of the parameters. It may be necessary to use a different order of the parameters depending on the target language due to wildly different grammars. Using {} would not allow this. ↩

2. This is an irritating problem in java.text.MessageFormat already as literal apostrophes must be doubled, otherwise the remaining parameters will not be filled in and the placeholder is printed instead. ↩

[hupfdule]

Note: We use the full (!) English message as key to ensure that the Java code is clear w.r.t. concrete message. Maybe, we could change that, but we were successful since approximately 10 years with that. [Details]

I have no objections regarding that approach. Kilt tries to not impose any specific style of localization. While the generated field names in a Kilt generated facade may be a bit unwieldy due to their length, they should still be rather usable, especially with IDE support.

May I ask what you intend to do with Kilt? Are you considering using it to create such a facade to be used in jabRef? Or do you consider using the import/export functionality from/to XLSX of Kilt?

[koppor]

May I ask what you intend to do with Kilt? Are you considering using it to create such a facade to be used in jabRef?

Yes. I was thinking if it was possible to drop all our localization-related tests (e.g., https://github.com/JabRef/jabref/blob/main/src/test/java/org/jabref/logic/l10n/LocalizationConsistencyTest.java) and to use a maintained library/eco system to foster synergy effects.

However, it seems that JabRef's handling is more sophisticated than I thought.

Or do you consider using the import/export functionality from/to XLSX of Kilt?

No, because we come along well with Crowdin 😅

[hupfdule]

OK. Can this issue be closed then? Or do you think there is still something to be done?

[koppor]

I closed it, but hope the explaining text would find its way to the documentation. 😅

[koppor]

My wish was

final String msgTemplate= i18n.get(Msg.ADDED_GROUP_0, theGroupName);

Thus, having java.text.MessageFormat.format integrated in i18n so that usage of translated strings is still a one-liner.