You are here: Internationalization API
Internationalization API
Internationalization is the process of enhancing an application to support multiple languages across various regions. Internationalization is abbreviated as i18n. The voltmx.i18n namespace provides a comprehensive set of functions for developing multilingual applications.
The Internationalization API uses voltmx.i18n Namespace and the following API elements.
| Function | Description |
|---|---|
| voltmx.i18n.deleteResourceBundle | Enables you to delete an existing resource bundle. |
| voltmx.i18n.getCurrentLocale | Returns the locale (string) that is currently being used by the application to populate the localized data. |
| voltmx.i18n.getCurrentDeviceLocale | Provides you the ability to fetch the current locale of the device. |
| voltmx.i18n.getLocalizedString | Returns the localized string that corresponds to the specified i18n Key. |
| voltmx.i18n.getSupportedLocales | Retrieves a list of all the locales supported by the device. |
| voltmx.i18n.isLocaleSupportedByDevice | Provides you the ability to view whether a locale is supported by a device. |
| voltmx.i18n.isResourceBundlePresent | Checks if a resource bundle exists for a given locale and returns a boolean value. |
| voltmx.i18n.setCurrentLocaleAsync | Provides you the ability to set the specified locale as the current locale of the application. |
| voltmx.i18n.setDefaultLocaleAsync | Enables you to set the specified locale as the default locale for the application. |
| voltmx.i18n.setLocaleLayoutConfig | Enables you to define the Right-To-Left (RTL) behavior for each locale in an application. |
| voltmx.i18n.setResourceBundle | Enables you to set the specified resource bundle for a given locale. |
| voltmx.i18n.updateResourceBundle | Enables you to append new key-value pairs to the given resource bundle for a specified locale. |
You can find the locales supported by a device. The voltmx.i18n.getSupportedLocales function fetches all the locales supported by a device. If you want to check whether a specific locale is supported by a device, use the voltmx.i18n.isLocaleSupportedByDevice function
There are two types of locales, device-specific locales and application-specific locales. Use the voltmx.i18n.getCurrentDeviceLocale function to find the current locale of a device. Fetch the current locale supported by an application using the voltmx.i18n.getCurrentLocale function. If you want to change the locale supported by an application, use the voltmx.i18n.setCurrentLocaleAsync function. You can set a default locale for an application by using the voltmx.i18n.setDefaultLocaleAsync function. Once a locale is set, configure the layout of your locale, and define the Right-To-Left behavior of the locale by using the voltmx.i18n.setLocaleLayoutConfig function.
Every locale comprises of a resource bundle. Check whether the selected locale contains a resource bundle using the voltmx.i18n.deleteResourceBundle function. If the locale does not contain a resource bundle, use the voltmx.i18n.setResourceBundle function to set a specific resource bundle for the locale. You can then update the resource bundle with new key-value pairs, by using the voltmx.i18n.updateResourceBundle function. To obtain a localized string corresponding to an i18n key, use the voltmx.i18n.getLocalizedString function.
Before you get started with using the voltmx.i18n namespace and functions, you should get to know a few things. They are, Resource bundle and Implementing i18N.
Note: From V9 SP2 onwards, the i18n database data for a Volt MX App child app is stored in child app data and not under the parent app. This feature is applicable for iOS, Windows, and Android platforms.
Resource Bundle
Resource bundle is a properties file that contains all the i18n Keys and their pair values. The resource bundle is locale specific, that is, you will have one resource bundle per locale. The resource bundle follows the naming convention of
- For English locale in United States, the resource bundle will be en_US.properties.
- For French locale in Canada, the resource bundle will be fr_CA.properties.
The resource bundle has a list of key-value pairs that are used as internationalization keys within the application.
Implementation Details
The current practice to support i18n for applications is to place the text (i18n keys) in the resource bundles that are loaded into the application. Applications are built to access the resource bundles depending on the selected locale data. For an application to support multiple languages, the application should be designed to select the relevant resource bundle at run-time. The keys in the resource bundles are translated to the required languages at run-time.
An internationalized application has the following benefits:
- The same application can run on multiple locales.
- Widget's text is not hard-coded in the application. Instead, the localized keys are retrieved dynamically.
- Support for new locales does not require recompilation.
- Region-dependent data such as dates and currencies appear in formats that conform to the end user's region and language.
To view the functionality of the Internationalization API in action, download the sample application from the link below. Once the application is downloaded, build and preview the application using the Volt MX App.
