T-Plan Robot Enterprise Localization Instructions

1. Introduction
2. Localization Framework Overview
3. Localization Example
4. Using Translation Memory

1. Introduction

This document describes how to localize T-Plan Robot Enterprise meaning how to translate the software messages (strings) into another language and how to plug them back to the product.

Be aware that unlike the open source version of T-Plan Robot, the Enterprise product is not ready to be fully localized. Though the mechanism described below will work fine and message files will be compatible accross the products, the software messages in Enterprise features were not extracted and will show in English only. This will be reimplemented provided that there is sufficient demand from our Enterprise customers.

2. Localization Framework Overview

T-Plan Robot Enterprise is localization ready in terms of ability to load and display translated software messages and help topics. The product is currently not ready to display/accept numbers and date in national formats (English format is always required).

All software messages (except the very low level logs and debugging messages) are concentrated in a single text file (called "resource bundle" in Java terminology) in the Java .properties format. The default English one is Messages_en.properties. There's also a custom mechanism allowing to load translated message files for different languages. Most of this functionality is implemented in the LocalizationSupport and ApplicationSupport classes.

T-Plan Robot Enterprise is compatible with the standard Java localization mechanism described in the java.util.Locale and java.util.PropertyResourceBundle documentation except for the mandatory file name prefix and slightly modified load functionality. Name of a resource bundle must start with a prefix Messages followed by a mandatory underscore ('_') and a language ISO-639 2-letter code. The file name can be further on extended with an optional underscore and country code (ISO-3166, 2-letter) which may be further on followed by an optional underscore and variant (which is a vendor or browser-specific code). Extension of the file name must be .properties and its content must conform to the Java Property File specification.

For example, an appropriate file name for generic English messages would be Messages_en.properties while file with messages in German spoken in Germany should be named Messages_de_DE.properties.

The product in addition enables to plug in resource bundles into the binaries without any code modification. When the tool starts, it looks in the install folder for custom resource bundles conforming to the file name convention before searching for the internal bundles in the com.tplan.robot package. That's why it is sufficient to copy any translated file(s) to the T-Plan Robot Enterprise installation path. If there's a name conflict with another message file bundled with the code, the outside one is preferred.

Help files are located in the help/ folder on the installation path. The default English help content is located under the help/en directory. There is a top level image directory help/images which contains localization independent application images, such as icons and logos. The content further on contains one or more image folders with application screenshots which may be recreated with localized ones.

Translated help files must be stored in subfolders named with the same language_country_variant suffix used for the resource bundles. The correct path for the example of German spoken in Germany should be help/de_DE. If the application is started on the de_DE locale, it looks for the corresponding help content in help/de_DE, then in help/deand it finally defaults to the English help content if no localized one is found.

Help content is defined by three files: HelpSet.hs, Map.jhm and TOC.xml. See the Sun Microsystem's JavaHelp documentation for information about function and content format of each single file. These files must be present in each language help folder. Their content may be however customized to deliver a different help content for a custom language version. Be just aware that many GUI components rely on existence of certain help topics (referred to through the keys defined by target attributes of Map.jhm). If you remove these keys from the map, help on such components will not be available.

There's no dependency between the localized help files and software messages. Both locale based loading mechanisms are independent and it is possible to deliver just translated messages, or just translated help content, or both.

3. Localization Example

An example of how to localize the application into Mexican Spanish follows:

Get the latest Messages_en.properties file from the product source code. If you don't have it, unzip the product JAR file from the product binaries and get it from there.
The file contains pairs like [key]=[message]. Translate just the messages. Lines starting with a hash '#' are comments. Follow the instructions in the file header describing how to handle certain special characters. It is recommended to use a translation memory (see the Using Translation Memory chapter for more).
Convert the translated file into escaped unicode using the native2ascii tool available in your JDK. It will replace all national (non-English) characters with \uXXXX sequences.
Rename the file to reflect your locale (i.e. your language or language/country combination). For Mexican Spanish the file should be called Messages_es_MX.properties.
Save the file to the T-Plan Robot Enterprise installation folder (to the directory where the product binaries are located).
Set your console locale to Mexican Spanish (export LC_ALL=es_MX.UTF-8; export LANG=es_MX on Linux/Unix machines) and start the application. It should pick up the new file and display its messages. Alternatively start the application in any other locale and select the desired language in the drop down of the Login Window. To specify the desired locale from CLI use the --locale switch.

It is also possible to zip the new resource bundle into the application JAR. It must be placed into the same folder where the English one is located. As it involves modification of product binaries, check if the terms of license allow it (GPL version is fine). If you decide to redistribute such a modified binary, make sure to license the translated file under a license compatible with the product license.

To localize the help content into Mexican Spanish:

Copy the help/en folder to help/es_MX.
Translate all (or just some) HTML files in the new folder.
Optionally recreate all images containing localizable text (typically located in the images/ subfolder of the HTML file directory).

4. Using Translation Memory

It is highly recommended to use a translation memory (TM) for translation. TMs allow to store strings translated in the past and reuse them. There are usually translation editors working on top of TMs which make the translation process easy and comfortable.

A good example is Sun Microsystem's Translation Editor which is being distributed as part of the Open Language Tools (OLT) project. It is free and open source under CDDL (as of Aug 2009), it supports the .properties format and it has some interesting features, such as fuzzy matching (non-exact search for translations in the translation database). Before you start to translate, optionally check the open source projects on the web whether there are some translation memories (meaning databases with translations) matching your target language and desired license. This can save you a lot of work. Be however aware that translations done by someone else are also copyrighted and licensed and make sure there's no conflict with your target license.