Use of Localized Texts in Applications

SAPUI5 provides two options to use localized texts in applications: The jQuery.sap.resources module and data binding.

Using jQuery.sap.resources

You can use the JavaScript module jQuery.sap.resources to access localized texts. The module contains APIs to load a resource bundle file from a given URL and for a given locale.

To make sure that the jQuery.sap.resources module is loaded, you have to require it as follows: 

#!jsjQuery.sap.require("jquery.sap.resources");

You can then use the jQuery.sap.resources function to load the resource bundle from the given URL, that is, the bundle name, and for a given locale. When no locale is specified, a default locale (en) is used. The following code snippet shows the use of the jQuery.sap.resources function to return a jQuery.sap.util.ResourceBundle: 

#!jsvar oBundle = jQuery.sap.resources({url : sUrl, locale: sLocale});

For more information, see jQuery.sap.resources in the API Reference.

The resource bundle jQuery.sap.util.ResourceBundle provides access to the localized texts that are contained in the resource bundle. You can use the getText method to access the texts in the loaded bundle by means of their key. This is shown in the following code snippet: 

#!jsvar sText = oBundle.getText(sKey);
Localization Test Page

The test suite provides a test page that shows how to use localized texts. This section only provides a short overview how the jQuery.sap.resources module is used there.

For a localized Web page you need the .html page itself and the .properties files of the required languages, in this example English and German.

The resource bundle i18n.properties is the English fallback version, which is the default version. 

#!propertieswelcome=Welcome {0}. Please enter a new contact:
lastname=Last Name:
firstname=First Name:
street=Street:
zip=ZIP:
city=City:

The resource bundle i18n_de.properties contains the texts in German. The following code snippet shows the content of this file: 

#!propertieswelcome=Willkommen {0}. Bitte geben Sie einen neuen Kontakt ein:
lastname=Nachname:
firstname=Vorname:
street=Straße:
zip=PLZ:
city=Ort:

The localization test page uses these texts to display a welcome message and a form to enter the address of a person. The coding of the test page looks as follows: 

#!jsjQuery.sap.require("jquery.sap.resources");
var sLocale = sap.ui.getCore().getConfiguration().getLanguage();
var oBundle = jQuery.sap.resources({url : "res/i18n.properties", locale: sLocale});
var oMatrixLayout = new sap.ui.commons.layout.MatrixLayout();
oMatrixLayout.setLayoutFixed(false);
oMatrixLayout.createRow(
  new sap.ui.commons.TextView({text: oBundle.getText("welcome", ["Administrator"])}) 
);
oMatrixLayout.getRows()[0].getCells()[0].setColSpan(2);
oMatrixLayout.createRow(
  new sap.ui.commons.Label({text: oBundle.getText("lastname")}), 
  new sap.ui.commons.TextField()
);
oMatrixLayout.createRow(
  new sap.ui.commons.Label({text: oBundle.getText("firstname")}), 
  new sap.ui.commons.TextField()
);
oMatrixLayout.createRow(
  new sap.ui.commons.Label({text: oBundle.getText("street")}), 
);
oMatrixLayout.createRow(
  new sap.ui.commons.Label({text: oBundle.getText("zip")}), 
  new sap.ui.commons.TextField()
);
oMatrixLayout.createRow(
  new sap.ui.commons.Label({text: oBundle.getText("city")}), 
  new sap.ui.commons.TextField()
);
oMatrixLayout.placeAt("userForm");

With regard to localization, the code above defines the following procedure:

  1. Require the jQuery.sap.resources module
  2. Determine the language
  3. Load the resource bundle
  4. Access the text using the welcome key and pass the value for the placeholder ({0}) via an array
  5. Access the text using the lastname key and set it as text for the Label
Data Binding

You can also use data binding to access localized texts. The ResourceModel is a wrapper for resource bundles that exposes the localized texts as a model for data binding. You use the ResourceModel to bind texts for control properties to language dependent resource bundle properties. You can instantiate the ResourceModel either with bundleName (name of a resource bundle that equals a SAPUI5 module name within the require/declare concept), or a bundleUrl, which points to a resource bundle. When you use the bundle name, make sure that the file has a .properties suffix. If no locale is defined, the current language is used.

Example 
#!jsvar oModel = new sap.ui.model.resource.ResourceModel({bundleName:"myBundle",bundleLocale:"en"});
var oControl = new sap.ui.commons.Button( {
    id : "myButton",
    text : "{i18n>MY_BUTTON_TEXT}"
});
// attach the resource model with the symbolic name "i18n"
oControl.setModel(oModel, "i18n");
Note The current data binding implementation does not allow to pass parameters to your texts in the resource bundle. If you have to pass parameters, you must do this on your own. You can, however, access the resource bundle directly from the model instead of loading it: 
#!jsvar myBundle = oModel.getResourceBundle()

After the instance has been created, you have a model containing the resource bundle texts as data.

For a complete overview of available methods and parameters, see ResourceModel in the API Reference in the Demo Kit

Related Information
Resource Model