Translating the TNTclient Interface

The TNTserver products lets you publish TNTatlas stacks on the internet or intranet for access from any browser.  When a browser accesses a TNTserver site, it automatically downloads TNTclient, which handles the special communication and display features required to view and navigate the atlas in the browser. 

The interface text of TNTclient can be translated into any language and character set by translating the TNTclient’s locale file.  When a web visitor begins using an atlas provided by the TNTserver, the protocols of the system can usually detect the language preference of the user’s computer and automatically present the interface in the correct language by selecting the appropriate locale file, if one has been prepared.  The user may also explicitly request any of the available language interfaces.  The default interface is in English.  MicroImages also has TNTclient locales for Japanese and Russian.  You can prepare a localization for any other language by following these instructions. 

Note that this localization applies to the language of the TNTclient interface: menus, buttons, labels, and messages.  It does not apply to the contents of the atlas stack.  For example, map annotations that were “hard-coded” by the author of the stack are not affected by the TNTclient localization. (Of course map annotations can be localized with the TNT products for any language and font.)  In the illustration below, the interface elements show in Russian, while the contents of the current map (such as the Agency Seal, and annotations) remain in English.

Much more detail on localization issues is provided in the booklet Getting Started: Localization from MicroImages Press.  You can view or download that booklet from the MicroImages website: http://www.microimages.com/getstart/localiz.htm.  Refer to that booklet, which treats issues of encoding, text editors, and locale file formats.  However, keep in mind that the booklet includes instructions for localizing the entire family of TNT products across Windows, Macintosh, and UNIX computer platforms, which is a larger task.  Some things needed to localize the TNT products in the X Window System environment, such as creating locale directories, are not needed to localize TNTclient for web browsers.

1. Create resource_xx.txt or resource_xx_YY.txt.

The default TNTclient locale file is resource.properties, which contains the English interface resources.   Make a copy of resource.properties that you can edit with a text editor that supports your target language and character set.  (Refer to Getting Started: Localization, pages 5 and 7.)

The file named resource.properties always contains the default English interface text.  Give your new locale file a name that complies with the ISO 639 and ISO 3166 language and country naming conventions.  Also, give your working copy a .txt file extension.

Language Code.  In most cases, you simply append the ISO 639 two-letter lower-case language code to the first part of the name with an underscore character (“_”), and use a .txt extension, in the form resource_ru.txt.  This .txt version of the file will have the character encoding used by your text editor that supports the characters of your target language.

You can view a complete list of ISO 639 language codes at http://www.w3.org/WAI/ER/IG/ert/iso639.htm.

Country Code.  In most cases, you need no more than the language code to identify your locale file.  However, if your translation is targeted for the language distinctives of a particular country (such as Canadian French as opposed to European French), you should also include the ISO 3166 two-letter upper-case country code, in the form resource_fr_CA.txt.  Use the country code only if your translation is targeted to the language distinctives of a specific country.  

You can view a complete list of ISO 3166 country codes at http://xml.coverpages.org/country3166.html

2. Translate the interface text.

Use your text editor to translate the interface text in your copy of resource.properties.   Your editor will use some encoding, such as UTF8, that supports the characters needed by your target language.

Translate only the interface text, which follows the “=” character on each line as illustrated above.  Do not change any of the resource keywords, which begin each line and have the form 1x_view.label, apply.label, and atlas_settings.label as illustrated above.

3. Convert Your Intermediate Locale File.

When you finish your translation, the file saved by your text editor must be converted to a special ASCII format that Java can use with TNTserver and TNTclient.  The Java Developer’s Kit contains a conversion utility named native2ascii.exe, which converts the UTF8 (or other) encoding of your translation into an ASCII file that contains the text’s code points in Unicode. 

If you do not have a Java Developer’s Kit, you can email your .txt version to MicroImages, and the special ASCII format will be created for you.  The ASCII version that Java uses with TNTclient needs the .properties extension (instead of the .txt extension of your intermediate working copy) and must include the correct ISO language code (and perhaps the ISO country code), in the form resource_fr_CA.properties, or resource_ru.properties.

Copy the ASCII version of your locale file to the computer that serves as your atlas server (the computer that runs TNTserver).  Put your locale file into the same directory that has the original resource.properties file (which must remain on the system).

4. Send Your Locale File to MicroImages.

MicroImages maintains a TNTserver website that has a variety of sample atlas stacks.   When you send your new locale file to MicroImages, all the existing atlases can automatically use it whenever a visitor’s browser needs that language.  Visitors may also request available locales explicitly.

Zip and email your locale file to info@microimages.com.  

5. Keeping Up-to-Date.

MicroImages continually updates and enhances TNTserver and TNTclient.  As new features are added, there will be new entries in the resource.properties file.  Periodically you should compare your version of the locale file to the most recent version on the MicroImages website.  Update and regenerate your locale file to support the complete set of TNTclient features. 

Java Precedence for Locale Selection

Java automatically selects the most appropriate locale file according to protocols that identify the language preference of the visitor’s browser.  Java first looks for a locale file for both language and country, such as resource_fr_CA.properties.  If that file is not found, or if that file does not contain an entry for the resource it needs, Java looks for its second preference: a locale file for the language, such as resource_fr.properties.  If that file is not found, or if that file does not contain an entry for the resource it needs, Java goes to the English default: resource.properties.  Thus it is possible that as it displays a single window, Java could draw from resources in three different versions of the locale file.

By design, you may choose to create locale files that contain only a few of the resource entries.  Thus you might create one complete resource file for French, and another, much smaller resource file for Canadian French, that contains only the entries for selected Canadian French exceptions or variations.  Java will look first in the Canadian French resource file (resource_fr_CA.properties), and then fall back to the general French file (resource_fr.properties) whenever the Canadian version lacks a resource entry.  Thus you can easily create a family of locale files that support several country variations without duplicating a large shared body of common language resources. 

25 March 2009

page update: 24 Aug 07

©MicroImages, Inc. 2010 Published in the United States of America
11th Floor - Sharp Tower, 206 South 13th Street, Lincoln NE 68508-2010   USA
Business & Sales: (402)477-9554  Support: (402)477-9562  Fax: (402)477-9559
Business info@microimages.com  Support support@microimages.com  Web webmaster@microimages.com

---