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".
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" 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 |
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. |
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" |
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 |
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 | 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 |
|
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 ( |
|
fallbackLocale | string | "en" |
A fallback locale to be used after all locales derived from |
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 |
|
activeTerminologies | string[] |
The list of active terminologies, e.g. |
|
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. |
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 |
|
bIgnoreKeyFallback | boolean | false |
If set, |
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 |