UI5 Web Components i18n for apps (valid since 1.0.0-rc.8)

Note: For information on how to setup i18n for your custom components, please see Developing Web Components.

The @ui5/webcomponents-base package allows the usage of i18n functionality not just for third-party UI5 components, but for apps as well.

Step by step tutorial

This tutorial will demonstrate how you can use the UI5 Web Components i18n functionality for the purpose of your apps.

1. Start by creating some i18n resources in a directory that can be served, for example:

File Content
assets/messagebundle_de.properties PLEASE_WAIT=Bitte warten
assets/messagebundle_fr.properties PLEASE_WAIT=Patientez.
assets/messagebundle_es.properties PLEASE_WAIT=Espere
assets/messagebundle_en.properties PLEASE_WAIT=Please wait
import parse from "@ui5/webcomponents-base/dist/PropertiesFileFormat.js";
import { registerI18nLoader, fetchI18nBundle, getI18nBundle  } from "@ui5/webcomponents-base/dist/asset-registries/i18n.js";

The first one provides support for .properties files, as used in the example and the second one - the functions that will allow you to take advantage of the i18n functionality.

3. Register a loader function that can retrieve and process the actual content of your message bundles:

const supportedLocales = ["en", "fr", "de", "es"];
supportedLocales.forEach(localeToRegister => {
	registerI18nLoader("myApp", localeToRegister, async (localeId) => {
		const props = await (await fetch(`./assets/messagebundle_${localeId}.properties`)).text();
		return parse(props);
	});
};

The first argument to resisterI18nLoader is an ID that will be used to reference this message bundle, the second is the locale this loader can load and the third is is a function that can load (and process) the content for the specified package/locale combination.

Note: For more assets, a loop is used to register a loader for each package/locale combination. The same loader function can be registered and its parameter can be used to distinguish which locale resource is requested.

Note: This step takes care of registering assets only, no data will be fetched at this point.

4. Tell the framework to fetch the texts for the current language:

await fetchI18nBundle("myApp");

This will fetch the appropriate texts for the currently configured language.

5. Get and use the bundle

const bundle = getI18nBundle("myApp");
const pleaseWait = bundle.getText("PLEASE_WAIT");
console.log("Please wait in the current language is: ", pleaseWait);

You can pass multiple additional values to getText for texts with placeholders, for example:

If your text looks like this:

CAROUSEL_DOT_TEXT=Item {0} of {1} displayed

you can call getText like this:

bundle.getText("CAROUSEL_DOT_TEXT", 5, 20);

which will finally result in, for example:

Item 5 of 20 displayed.

6. Test your page using different languages, f.e. set ?sap-ui-language=de in the URL or change the configuration.

Summary

The whole code would look like this:

import parse from "@ui5/webcomponents-base/dist/PropertiesFileFormat.js";
import { registerI18nLoader, fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";

const supportedLocales = ["en", "fr", "de", "es"];
supportedLocales.forEach(localeToRegister => {
	registerI18nLoader("myApp", localeToRegister, async (localeId) => {
		const props = await (await fetch(`./assets/messagebundle_${localeId}.properties`)).text();
		return parse(props);
	});
};

await fetchI18nBundle("myApp");

const bundle = getI18nBundle("myApp");

const pleaseWait = bundle.getText("PLEASE_WAIT");
console.log("Please wait in the current language is: ", pleaseWait);

You register your assets for all supported languages, then you fetch the data for the currently active language, get a reference to the bundle and call the getText method to get texts for your app.

Tips and tricks

  • You can skip the .properties format support import
return await (await fetch(`./assets/messagebundle_${localeId}.json`)).json();

and return the data directly in .json format, if you want to load a little bit less code in the runtime.

File Content
assets/messagebundle_de.json {"PLEASE_WAIT": "Bitte warten"}
assets/messagebundle_fr.json {"PLEASE_WAIT": "Patientez."}
assets/messagebundle_es.json {"PLEASE_WAIT": "Espere"}
assets/messagebundle_en.json {"PLEASE_WAIT": "Please wait"}