Global i18n / L10n for Vaadin components

[rolfsmeds]

Description

Localize Vaadin components using the same i18n provider that you use for the rest of your UI.

Tier

Free

License

Apache 2.0

Motivation

Background

Localization (L10n) and internationalization (i18n) of Vaadin components is currently based on i18n objects that are configured separately for each locale (e.g. language) and applied separately to each instance of each component in the UI:

Flow:

DatePickerI18n germanI18n = new DatePickerI18n()  
    	.setToday("Heute")  
    	.setCancel("Abbrechen")  
    	.setFirstDayOfWeek(1)  
    	.setMonthNames(Arrays.asList("Januar", "Februar", ...

datePicker.setI18n(germanI18n);

The rest of the UI, on the other hand, is typically managed through an i18nProvider that replaces translation keys used in the UI with the corresponding text for the current locale. The default i18nProvider uses translation property files in the src/main/resources/vaadin-i18n directory, but the source could just as well be e.g. a database.

Translation property file translation_de_DE.properties

field.firstname=Vorname
field.lastname=Nachname
btn.cancel=Abbrechen
btn.save=Speichern
btn.close=Schließen
employees-view.title=Mitarbeiter
employees.section.address=Adresse
field.address.city=Stadt
field.address.state=Bundesland

Flow:

firstNameField.setLabel(translate(`field.firstname`));

Problem

• There is no global method for configuring all instances of a component at once. Developers need to configure each instance of a component individually, which increases boilerplate.
• When the locale of the UI changes, developers need to manually update the I18N object in each component instance again, adding more boilerplate.
• For any large scale application, every team will probably invent their own abstractions to reduce that boilerplate.
• The current mechanism is prone to errors. Developers may forget to configure I18N in a specific component instance, or may unintentionally or unknowingly use a different I18N configuration for a component instance.
• It is completely separate from the approach typically used to localize the rest of the UI (i.e. strings fetched based on translation keys via an I18nProvider, most commonly from translation property files).

Solution

• Components automatically fetch localized strings from the same i18nProvider that is used for the rest of the application UI.
• Each component has a hardcoded set of translation keys used to fetch localized strings.
• To avoid clashes with other translation keys in the application, Vaadin components' keys are prefixed e.g. with vaadin.components. These will be listed in the documentation for each component.
• Each string also has a hardcoded default value (in English) that is used as a fallback if no translation is found.
• I18n properties that are not text, such as the firstDayOfWeek property for DatePicker, can also be handled this way as long as they can be represented as text.
• i18n objects will continue to be supported. If an i18n object is provided for a component instance, translations in it have priority over the i18nProvider.
• Ideally, the strings are automatically updated through the same mechanism whenever the UI's locale changes.

As an example, all that is required to localize every DatePicker instance to German is to provide values for their translation keys in the same place as the rest of the UI, e.g. in a translation property file:

vaadin.components.datePicker.today = Heute
vaadin.components.datePicker.cancel = Abbrechen
vaadin.components.datePicker.firstDayOfWeek = 1
vaadin.components.datePicker.monthNames = Januar,Februar,...

Requirements

• Values for all internationalized properties in Vaadin components are automatically fetched from the i18nProvider used in the application, if one is available.

• i18n objects applied to component instances have priority.

• Hardcoded English defaults are used if no translation is found.

• Non-text properties can be parsed from string representations.

• Documentation: Flow and Hilla localization documentation is updated to reflect this feature, and each component's documentation includes a list of translation keys.

Nice-to-haves

• Components automatically refresh their i18n property values when the locale changes.

Risks, limitations and breaking changes

Risks

• Implementation approach for Hilla/React is still quite uncertain.
• We might at some point want to introduce new I18N properties that are not compatible with being retrieved as a string through the translation APIs, although we are not currently aware of any such needs.
• There’s a minor risk that translation keys we define clash with application-specific ones.

Limitations

Breaking changes

None expected.

Out of scope

No response

Materials

• RFC (internal access only)

Metrics

No response

Pre-implementation checklist

• Estimated (estimate entered into Estimate custom field)
• Product Manager sign-off
• Engineering Manager sign-off

Pre-release checklist

• Documented (link to documentation provided in sub-issue or comment)
• UX/DX tests conducted and blockers addressed
• Approved for release by Product Manager

Security review

None