2. Localization Framework Overview
3. Localization Example
4. Using Translation Memory
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.
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
There's also a custom mechanism allowing to load translated
message files for different languages. Most of this functionality is
implemented in the
T-Plan Robot Enterprise is compatible with the standard Java
localization mechanism described in the
documentation except for the mandatory file name prefix and slightly
functionality. Name of a resource bundle must start with a prefix
followed by a mandatory underscore ('_') and a
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
Messages_en.properties while file with messages
in German spoken in Germany should be named
The product in addition enables to plug
in resource bundles into the
binaries without any code modification. When the tool starts, it
in the install folder for custom resource bundles conforming to the
file name convention before searching for the internal bundles in the
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
outside one is preferred.
Help files are located in
help/ folder on the installation path. The default
English help content is located under the
There is a top level image directory
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
and 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
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.
An example of how to localize the application into Mexican Spanish follows:
Messages_en.propertiesfile 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.
native2asciitool available in your JDK. It will replace all national (non-English) characters with \uXXXX sequences.
export LC_ALL=es_MX.UTF-8; export LANG=es_MXon 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
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
To localize the help content
into Mexican Spanish:
images/subfolder of the HTML file directory).
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