class sap/base/i18n/ResourceBundle

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Extends:
Module: sap/base/i18n/ResourceBundle
Application Component:

Contains locale-specific texts.

If you need a locale-specific text within your application, you can use the resource bundle to load the locale-specific file from the server and access the texts of it.

Use module:sap/base/i18n/ResourceBundle.create to create an instance of sap/base/i18n/ResourceBundle (.properties without any locale information, e.g. "mybundle.properties"), and optionally a locale. The locale is defined as a string of the language and an optional country code separated by underscore (e.g. "en_GB" or "fr"). If no locale is passed, the default locale is "en" if the SAPUI5 framework is not available. Otherwise the default locale is taken from the SAPUI5 configuration.

With the getText() method of the resource bundle, a locale-specific string value for a given key will be returned.

With the given locale, the resource bundle requests the locale-specific properties file (e.g. "mybundle_fr_FR.properties"). If no file is found for the requested locale or if the file does not contain a text for the given key, a sequence of fallback locales is tried one by one. First, if the locale contains a region information (fr_FR), then the locale without the region is tried (fr). If that also can't be found or doesn't contain the requested text, a fallback language will be used, if given (defaults to en (English), assuming that most development projects contain at least English texts). If that also fails, the file without locale (base URL of the bundle, often called the 'raw' bundle) is tried.

If none of the requested files can be found or none of them contains a text for the given key, then the key itself is returned as text.

Exception: Fallback for "zh_HK" is "zh_TW" before "zh".


Constructor


Methods Overview

Method Description
module:sap/base/i18n/ResourceBundle._getFallbackLocales

Determine sequence of fallback locales, starting from the given locale and optionally taking the list of supported locales into account.

Callers can use the result to limit requests to a set of existing locales.

module:sap/base/i18n/ResourceBundle._getUrl

Gets the URL either from the given resource bundle name or the given resource bundle URL.

module:sap/base/i18n/ResourceBundle.create

Creates and returns a new instance of module:sap/base/i18n/ResourceBundle using the given URL and locale to determine what to load.

Before loading the ResourceBundle, the locale is evaluated with a fallback chain. Sample fallback chain for locale="de-DE" and fallbackLocale="fr_FR" "de-DE" -> "de" -> "fr_FR" -> "fr" -> raw

Only those locales are considered for loading, which are in the supportedLocales array (if the array is supplied and not empty).

Note: The fallbackLocale should be included in the supportedLocales array.

getText

Returns a locale-specific string value for the given key sKey.

The text is searched in this resource bundle according to the fallback chain described in module:sap/base/i18n/ResourceBundle. If no text could be found, the key itself is used as text.

If the second parameter aArgs is given, then any placeholder of the form "{n}" (with n being an integer) is replaced by the corresponding value from aArgs with index n. Note: This replacement is applied to the key if no text could be found. For more details on the replacement mechanism refer to module:sap/base/strings/formatMessage.

hasText

Checks whether a text for the given key can be found in the first loaded resource bundle or not. Neither the custom resource bundles nor the fallback chain will be processed.

This method allows to check for the existence of a text without triggering requests for the fallback locales.

When requesting the resource bundle asynchronously this check must only be used after the resource bundle has been loaded.

module:sap/base/i18n/ResourceBundle._getFallbackLocales

Determine sequence of fallback locales, starting from the given locale and optionally taking the list of supported locales into account.

Callers can use the result to limit requests to a set of existing locales.

Param Type DefaultValue Description
sLocale string

Locale to start the fallback sequence with, should be a BCP47 language tag

aSupportedLocales string[]

List of supported locales (in JDK legacy syntax, e.g. zh_CN, iw)

sFallbackLocale string

Last fallback locale, defaults to "en"

module:sap/base/i18n/ResourceBundle._getUrl

Gets the URL either from the given resource bundle name or the given resource bundle URL.

Param Type DefaultValue Description
bundleUrl string

URL pointing to the base ".properties" file of a bundle (".properties" file without any locale information, e.g. "../../i18n/mybundle.properties"); relative URLs are evaluated relative to the document.baseURI

bundleName string

UI5 module name in dot notation referring to the base ".properties" file; this name is resolved to a path like the paths of normal UI5 modules and ".properties" is then appended (e.g. a name like "myapp.i18n.myBundle" can be given); relative module names are not supported

module:sap/base/i18n/ResourceBundle.create

Creates and returns a new instance of module:sap/base/i18n/ResourceBundle using the given URL and locale to determine what to load.

Before loading the ResourceBundle, the locale is evaluated with a fallback chain. Sample fallback chain for locale="de-DE" and fallbackLocale="fr_FR" "de-DE" -> "de" -> "fr_FR" -> "fr" -> raw

Only those locales are considered for loading, which are in the supportedLocales array (if the array is supplied and not empty).

Note: The fallbackLocale should be included in the supportedLocales array.

Param Type DefaultValue Description
mParams object

Parameters used to initialize the resource bundle

url string ''

URL pointing to the base .properties file of a bundle (.properties file without any locale information, e.g. "mybundle.properties") if not provided, bundleUrl or bundleName can be used; if both are set, bundleName wins

bundleUrl string

URL pointing to the base .properties file of a bundle (.properties file without any locale information, e.g. "i18n/mybundle.properties")

bundleName string

UI5 module name in dot notation pointing to the base .properties file of a bundle (.properties file without any locale information, e.g. "i18n.mybundle")

locale string

Optional locale (aka 'language tag') to load the texts for. Can either be a BCP47 language tag or a JDK compatible locale string (e.g. "en-GB", "en_GB" or "en"). Defaults to the current session locale if sap.ui.getCore is available, otherwise to the provided fallbackLocale

includeInfo boolean false

Whether to include origin information into the returned property values

supportedLocales string[]

List of supported locales (aka 'language tags') to restrict the fallback chain. Each entry in the array can either be a BCP47 language tag or a JDK compatible locale string (e.g. "en-GB", "en_GB" or "en"). An empty string ("") represents the 'raw' bundle. Note: The given language tags can use modern or legacy ISO639 language codes. Whatever language code is used in the list of supported locales will also be used when requesting a file from the server. If the locale contains a legacy language code like "sh" and the supportedLocales contains [...,"sr",...], "sr" will be used in the URL. This mapping works in both directions.

fallbackLocale string "en"

A fallback locale to be used after all locales derived from locale have been tried, but before the 'raw' bundle is used. Can either be a BCP47 language tag or a JDK compatible locale string (e.g. "en-GB", "en_GB" or "en"). To prevent a generic fallback, use the empty string (""). E.g. by providing fallbackLocale: "" and supportedLocales: ["en"], only the bundle "en" is requested without any fallback.

terminologies Object<string,module:sap/base/i18n/ResourceBundle.TerminologyConfiguration>

map of terminologies. The key is the terminology identifier and the value is a ResourceBundle terminology configuration. A terminology is a resource bundle configuration for a specific use case (e.g. "oil"). It does neither have a fallbackLocale nor can it be enhanced with enhanceWith.

activeTerminologies string[]

The list of active terminologies, e.g. ["oil", "retail"]. The order in this array represents the lookup order.

enhanceWith module:sap/base/i18n/ResourceBundle.Configuration[]

List of ResourceBundle configurations which enhance the current one. The order of the enhancements is significant, because the lookup checks the last enhancement first. Each enhancement represents a ResourceBundle with limited options ('bundleUrl', 'bundleName', 'terminologies', 'fallbackLocale', 'supportedLocales'). Note: supportedLocales and fallbackLocale are inherited from the parent ResourceBundle if not present.

async boolean false

Whether the first bundle should be loaded asynchronously Note: Fallback bundles loaded by #getText are always loaded synchronously.

getText

Returns a locale-specific string value for the given key sKey.

The text is searched in this resource bundle according to the fallback chain described in module:sap/base/i18n/ResourceBundle. If no text could be found, the key itself is used as text.

If the second parameter aArgs is given, then any placeholder of the form "{n}" (with n being an integer) is replaced by the corresponding value from aArgs with index n. Note: This replacement is applied to the key if no text could be found. For more details on the replacement mechanism refer to module:sap/base/strings/formatMessage.

Param Type DefaultValue Description
sKey string

Key to retrieve the text for

aArgs any[]

List of parameter values which should replace the placeholders "{n}" (n is the index) in the found locale-specific string value. Note that the replacement is done whenever aArgs is given, no matter whether the text contains placeholders or not and no matter whether aArgs contains a value for n or not.

bIgnoreKeyFallback boolean false

If set, undefined is returned instead of the key string, when the key is not found in any bundle or fallback bundle.

hasText

Checks whether a text for the given key can be found in the first loaded resource bundle or not. Neither the custom resource bundles nor the fallback chain will be processed.

This method allows to check for the existence of a text without triggering requests for the fallback locales.

When requesting the resource bundle asynchronously this check must only be used after the resource bundle has been loaded.

Param Type DefaultValue Description
sKey string

Key to check