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
  2. Import the following i18n-related modules to your app:

     import "@ui5/webcomponents-base/dist/features/PropertiesFormatSupport.js";
     import { registerI18nBundle, fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.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 your message bundles:

     registerI18nBundle("myApp", {
         de: "./assets/messagebundle_de.properties",
         es: "./assets/messagebundle_es.properties",
         fr: "./assets/messagebundle_fr.properties",
         en: "./assets/messagebundle_en.properties",
     });
    

    The first argument is an ID that will be used to reference this message bundle and the second, an object, providing the URLs where the i18n assets can be found.

    Note: This is just asset registration, no data will be fetched at that point.

  4. 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 "@ui5/webcomponents-base/dist/features/PropertiesFormatSupport.js";
import { registerI18nBundle, fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";

registerI18nBundle("myApp", {
	de: "./assets/messagebundle_de.properties",
	es: "./assets/messagebundle_es.properties",
	fr: "./assets/messagebundle_fr.properties",
	en: "./assets/messagebundle_en.properties",
});

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
 import "@ui5/webcomponents-base/dist/features/PropertiesFormatSupport.js";

and provide 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"}