Internationalization API

Internationalization is the process of enhancing an application to support multiple languages across various regions. Internationalization is abbreviated as i18n. The kony.i18n namespace provides a comprehensive set of functions for developing multilingual applications.

The Internationalization API uses kony.i18n namespace and the following API elements.

Function	Description
kony.i18n.deleteResourceBundle	Enables you to delete an existing resource bundle.
kony.i18n.getCurrentLocale	Returns the locale (string) that is currently being used by the application to populate the localized data.
kony.i18n.getCurrentDeviceLocale	Provides you the ability to fetch the current locale of the device.
kony.i18n.getLocalizedString	Returns the localized string that corresponds to the specified i18n Key.
kony.i18n.getSupportedLocales	Retrieves a list of all the locales supported by the device.
kony.i18n.isLocaleSupportedByDevice	Provides you the ability to view whether a locale is supported by a device.
kony.i18n.isResourceBundlePresent	Checks if a resource bundle exists for a given locale and returns a boolean value.
kony.i18n.setCurrentLocaleAsync	Provides you the ability to set the specified locale as the current locale of the application.
kony.i18n.setDefaultLocaleAsync	Enables you to set the specified locale as the default locale for the application.
kony.i18n.setLocaleLayoutConfig	Enables you to define the Right-To-Left (RTL) behavior for each locale in an application.
kony.i18n.setResourceBundle	Enables you to set the specified resource bundle for a given locale.
kony.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 kony.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 kony.i18n.isLocaleSupportedByDevice function

There are two types of locales, device-specific locales and application-specific locales. Use the kony.i18n.getCurrentDeviceLocale function to find the current locale of a device. Fetch the current locale supported by an application using the kony.i18n.getCurrentLocale function. If you want to change the locale supported by an application, use the kony.i18n.setCurrentLocaleAsync function. You can set a default locale for an application by using the kony.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 kony.i18n.setLocaleLayoutConfig function.

Every locale comprises of a resource bundle. Check whether the selected locale contains a resource bundle using the kony.i18n.deleteResourceBundle function. If the locale does not contain a resource bundle, use the kony.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 kony.i18n.updateResourceBundle function. To obtain a localized string corresponding to an i18n key, use the kony.i18n.getLocalizedString function.

Before you get started with using the kony.i18n namespace and functions, you should get to know a few things. They are, Resource bundle and Implementing i18N.

NOTE: From V8 SP4 onwards, the i18n database data for a Quantum App child app is stored in child app data and not under the parent app. This feature is applicable for iOS 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 <language_Country>.properties. For example,

• 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 Quantum App.