Localization

Internationalization

Internationalization is the process of designing an application so that it can be adapted to various languages and regions without engineering changes. Sometimes the term internationalization is abbreviated as i18n, because there are 18 letters between the first “i” and the last “n.”

The HEAT LiveTime product is an internationalized program that has the following characteristics:

  • With the addition of localized data, the same executable can run worldwide.
  • Textual elements, such as status messages and the GUI component labels, are not hardcoded in the program. Instead they are stored outside the source code and retrieved dynamically.
  • Support for new languages does not require recompilation.
  • Culturally-dependent data, such as dates and currencies, appear in formats that conform to the end user’s region and language.
  • HEAT LiveTime can be localized quickly.

Localization is the process of adapting software for a specific region or language by adding locale-specific components and translating text. The term localization is often abbreviated as l10n, because there are 10 letters between the “l” and the “n.”

The HEAT LiveTime internationalized framework is very intuitive and flexible, allowing Users to localize it for a particular language and character encoding scheme.

Getting Started

The primary task of Users performing localization of the HEAT LiveTime application is translating the user interface elements in the external text file – LiveTime.properties.

The following steps guide you through the localization process. We will assume a French localization for this example, which uses the ISO-8859-1 character set.

  • Ensure you have the appropriate character set installed on your Desktop’s Operating System. The localization file and rendering will both require the character set to be available for data entry and data presentation.
  • Ensure your RDBMS has been created using the appropriate character set, usually UTF-8. This is required so that French data entry can be successfully saved and retrieved from the database.
  • Specify the correct character set encoding for HEAT LiveTime. Edit the ‘Properties’ file (/CONTAINER_APPS_PATH>/Service/WEB-INF/Service.woa/Contents/Resources folder) and specify the character set to use for presentation to the end user. This character set will be sent to the end users to control presentation in both the user interface and outbound email.

Customizing Strings

The ‘LiveTime.properties’ file (/CONTAINER_APPS_PATH>/LiveTime/WEB-INF/LiveTime.woa/Contents/Resources folder) stores the externalized user interface content. This file is stored in plain text, the default (English) is encoded using the ISO-8859-1 character set. You can create alternative versions of this file in any text editor, that allows the file to be saved in the necessary character set.

The first step in creating a local version of this file is to save a copy of it representing the appropriate language. Being a French translation, there is no need to worry about the file encoding, so simply save a copy of the file called ‘LiveTime_fr.properties’.

The names of the localized files do follow a standard. In our example of French, LiveTime_fr.properties was the resultant file name. The ‘fr’ component of this name comes from iso 639-1. A full list of these codes is available here.

Simple Messages

The copy of this file consists of a collection of name-value pairs, each are broken up into clusters representing user interface components. For example:

ClassName.greetings=Hello
ClassName.farewell=Goodbye
ClassName.inquiry=How are you?

The ‘name’ or ‘key’ section (ClassName.greetings) of these strings is of little relevance to the end user. They are simply markers inside the application representing where each string goes.

The ‘value’ component of these pairs (Hello) represents the corresponding user interface value. The (French) translator can safely edit these values and they will appear within HEAT LiveTime.

ClassName.greetings=Bonjour.
ClassName.farewell=Au revoir.
ClassName.inquiry=Comment allez-vous?

Compound Messages

Compound messages contain variable data – i.e. data that HEAT LiveTime will substitute into the message at run time. For example, given the message ‘Hello Sunshine’, the string Sunshine may vary. This message is difficult to translate because the position of the string in the sentence is not the same in all languages, or alternatively the value may need to be generated by HEAT LiveTime based on some business logic.

Where this substitution is necessary, the localized strings will have a set of braces containing an id number (a substitution variable). These blocks will be replaced at run time by HEAT LiveTime and are identified by their presence. The localized version of a given String must contain the same number of substitution variables.

For example:

ClassName.helloSunshine=hello {0}

This will render as “hello sunshine”, however we could modify this message to read “sunshine, hello” by doing this:

ClassName.helloSunshine={0}, hello

Locales

The ‘LiveTimeLocales.xml’ file (/CONTAINER_APPS_PATH>/LiveTime/WEB-INF/LiveTime.woa/Contents/Resources folder) defines the language code and charset used in order to process the strings defined in the external properties file.

Typically, this will be the charset used when saving the external properties file.

By default the following language locale is selected:

<LOCALE language="en" country="" charset="ISO-8859-1"/>

To enable our French external properties file to behave correctly, we will need to uncomment the following line:

<LOCALE language="fr" country="" charset="UTF-8"/>

This will enable the application to use both English and French based on the users browser and operating system settings. For convenience, many values are already supplied in this file so it’s just a matter of uncommenting the necessary entry.

If an entry for your locale language doesn’t exist, then you can define it in this file by supplying the language code, country code, and charset, as illustrated in the above examples.

Instructions for setting browser locales is outside the scope of this document as each browser / OS combo handles this differently.