API Classes for Localization

General Interface provides the following classes for localizing applications:

• jsx3.util.Locale
• jsx3.util.DateFormat
• jsx3.util.MessageFormat
• jsx3.util.NumberFormat
• jsx3.app.PropsBundle

For more information on these classes, see General Interface API Reference (Help > API Documentation).

jsx3.util.Locale

General Interface 3.2 introduced a new class, jsx3.util.Locale, which represents a locale. A locale is a region of the world that shares a common language, writing, calendar, and so on. A locale is represented with a locale key, such as es_ES for Spanish in Spain. See Locale Keys.

The General Interface system, jsx3.lang.System, has a locale which determines the language and formatting of system messages. By default, the system locale is set automatically to the locale of the host web browser. However, the locale can be changed by calling the System.setLocale() method.

Each General Interface application, which is an instance of jsx3.app.Server, also has a locale. The server locale determines the locale of localized GUI controls that it contains. The application locale also determines which locale-sensitive resources are loaded into the application.

Locale Keys

The locale key is the string representation of a locale, which includes a language or a language and a country in one of the following formats:

• ll
• ll_CC

where ll is a lowercase, two letter, ISO 639 language code and CC is the optional, uppercase, two letter, ISO 3166 country code.

For a list of codes, visit these web sites:

• International Organization for Standardization (ISO) - http://www.iso.ch/iso/en/ISOOnline.frontpage
• Language codes - http://www.loc.gov/standards/iso639-2/langhome.html
• Country codes - http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html

DateFormat, NumberFormat, and MessageFormat

Three classes in the jsx3.util package form the foundation of the internationalization and localization services of General Interface: DateFormat, MessageFormat, and NumberFormat. These classes are internationalized, because they have a constructor that takes an arbitrary locale object as a parameter. The behavior of an instance of each class is dependent on the specified locale.

General Interface leverages data from the Common Locale Data Repository to localize these classes. The following locales from the CLDR are included with General Interface.

General Interface Locales

DateFormat

The DateFormat class formats and parses dates in a localized manner. Months and days of the week are localized. Additionally, factory methods are available for creating formats that are appropriate for a particular locale.

NumberFormat

The NumberFormat class formats numbers in a localized manner. Number symbols, such as the negative sign, decimal symbol, and percent symbol, are also localized. In addition, factory methods are available for creating formats that are appropriate for a particular locale.

MessageFormat

The MessageFormat class constructs messages from a format and various inputs. It's localized, because it can format inputs according to both DateFormat and NumberFormat.

jsx3.app.PropsBundle

The jsx3.app.PropsBundle class handles localized loading of resources. A localized resource is a collection of dynamic properties files that define a set of properties localized for one or more locales. For an example of a properties bundle file, see GI_HOME/JSX/locale/locale.xml.

The directory structure of a properties bundle is as follows:

• bundle_name.xml - the file containing the properties of the default locale and metadata describing the locales that are available in other files. For example, locale.xml.
• bundle_name.locale_key1_.xml - the file containing properties localized for locale locale_key1. For example, locale.fr.xml.
• bundle_name.locale_key2_.xml - the file containing properties localized for locale locale_key2. For example, locale.es.xml.

The default locale file in the properties bundle should be formatted as follows:

<!-- The "jsxnamespace" attribute is required to be "propsbundle"
The "locales" attribute is a comma separated list of locale
keys for which there exist files in this properties bundle. -->
<data jsxnamespace="propsbundle"
locales="external_locale_key1,external_locale_key2,...">
  <!-- The default locale omits the "key" attribute. -->
  <locale>
    <record jsxid="prop_key1" jsxtext="prop_value1" eval="0|1"/>
    ...
  </locale>

  <!-- Optionally define other locales in the same file. -->
  <locale key="locale_key">
    ...
  </locale>
    ...

</data>

Any other file in the same properties bundle should be formatted as follows:

<data jsxnamespace="propsbundle">
  <!-- The file must define properties for the locale for which the
     file is named. -->
  <locale key="external_locale_key1">
    ...
  </locale>
  <!-- Optionally, the same file may also define properties for
     subordinate locales. For example, if the above locale is "en"
     then it could be followed by "en_US", "en_GB", "en_AU", etc.
     -->
  <locale key="locale_key_country1">
    ...
  </locale>
  <locale key="locale_key_country2">
    ...
  </locale>
    ...
</data>

PropsBundle.getProps()

An instance of the PropsBundle class is obtained programmatically with the static factory method, PropsBundle.getProps(). The first argument for this method is the base path of the localized resource. In this example, it would be bundle_name.xml preceded by the path to the directory containing the bundle. For example, path_to_bundle/locale.xml. The second argument is an instance of jsx3.util.Locale. The factory method loads the files appropriate for the requested locale based on the metadata contained in the default locale. For more information, see General Interface API Reference.

Key Fall-through

The PropsBundle class provides for key fall-through. If a key isn't found in the properties file of a particular locale, the value from the next less-specific locale is used. For example, if an instance of PropsBundle with a locale of en_GB is queried for a key, it checks the properties of locale en_GB. If the key isn't found, it checks en, and finally, the properties of the default locale until a key is found.