Introduction

The localize utility is a simple command-line tool created to help non-programmers to localize well-written Java^TM applications.

If a Java application is delivered using one or several .jar files and if some of these Jar files contain .properties resource files, the localize utility may be applied to the Jars. Note that Java source code is not needed, neither is a JDK (Java Development Kit).

For modularity reasons, Java applications are localized at the class (example: a dialog box class) or at the package level (example: a framework of tightly coupled classes) by creating a text file with extension .properties for each class or package to be localized.

These .properties files contain key=value pairs, where key is the identifier of a message, button label or menu item and value is the localized text.

Each language supported by the Java application must have its own .properties variant. Example: Foo.properties for the default language (generally English), Foo_fr.properties for French, Foo_es.properties for Spanish and so on.

For a mid-size Java application, one may end up with dozens of such .properties files. Without the help of the localize utility, adding support for a new language, say German, means creating dozens of *_de.properties files, which is tedious and error-prone.

Three steps are needed to localize a Java application:

1. Using the localize utility, extract all the messages in a given language from the Jar (example: English, if English is the reference language of the application).

   ++++++++++com/xmlmind/xmleditapp/TagChooserDialogRes.properties
   
   error=Error
   error=
   
   invalidTag={0} is not a valid name
   invalidTag=
   
   ----------com/xmlmind/xmleditapp/TagChooserDialogRes.properties
   ++++++++++com/xmlmind/xmleditapp/ValidityDiagToolRes.properties
   
   close=Close
   close=
   
   title=Check validity
   title=
   
   ----------com/xmlmind/xmleditapp/ValidityDiagToolRes.properties

2. Using a text editor, fill-in the blanks in the extracted message file by translating each message to the new language.

   ++++++++++com/xmlmind/xmleditapp/TagChooserDialogRes.properties
   
   error=Error
   error=
   
   invalidTag={0} is not a valid name
   invalidTag=
   
   ----------com/xmlmind/xmleditapp/TagChooserDialogRes.properties
   ++++++++++com/xmlmind/xmleditapp/ValidityDiagToolRes.properties
   
   close=Close
   close=
   
   title=Check validity
   title=
   
   ----------com/xmlmind/xmleditapp/ValidityDiagToolRes.properties

3. Using a text editor, fill-in the blanks in the extracted message file by translating each message to the new language.

   ++++++++++com/xmlmind/xmleditapp/TagChooserDialogRes.properties
   
   error=Error
   error=Erreur
   
   invalidTag={0} is not a valid name
   invalidTag={0} n'est pas un nom valide.
   
   ----------com/xmlmind/xmleditapp/TagChooserDialogRes.properties
   ++++++++++com/xmlmind/xmleditapp/ValidityDiagToolRes.properties
   
   close=Close
   close=Fermer
   
   title=Check validity
   title=Vérifier validité
   
   ----------com/xmlmind/xmleditapp/ValidityDiagToolRes.properties

4. Using the localize utility, patch the Jar with the edited message file. (The localize utility adds appropriate .properties files to the Jar.)

The localize utility, while in the public domain, is fully supported by its author (hussein AT pixware DOT com).

Install

Installing localize

Requirements

• Sun or IBM Java 1.3 or above.
• 1Mb of free disk space.

The localize utility has been tested with:

• Sun Java 1.4 and 1.4.1 under SuSE Linux 7.2.
• Sun Java 1.3.0_02 under Windows NT SP5.

Install on Unix

Procedure:

1. Unpack the localize distribution somewhere.

   $ cd 
   $ unzip localize-12.zip
   $ ls localize-12
   Localizer.java
   doc.html
   localize
   localize.bat
   localize.jar

2. Copy the localize shell script and *.jar to a directory referenced in your path (example /usr/local/bin).

   $ su
   $ cp ~/localize-12/localize /usr/local/bin
   $ cp ~/localize-12/*.jar /usr/local/bin
   $ chmod a+rx /usr/local/bin/localize
   $ chmod a+r /usr/local/bin/*.jar

Install on Windows

Install on Windows is similar to the install on Unix but under Windows you'll have to copy localize.bat rather than the localize shell script.

Content of the distribution

localize, localize.bat

Scripts used to run this utility. (Use localize on any Unix system. Use localize.bat on Windows.)

localize.jar

contains the executable code of this utility.

Localizer.java

contains the source code of this utility.

doc.html

This user guide.

Command reference

localize ?options? jar_or_dir_name

Extract mode options are:

-x message_file

Extract messages to file message_file. Default: extract to console.

-l lang

Extract messages from '*_lang.properties'. Default: Extract from '[^_.]*.properties'.

-l2 lang2

If found, append corresponding message from '*_lang2.properties' after each message from '*_lang.properties'. Default: Append placeholder.

Patch mode options are:

-p message_file

Read messages from file message_file. Default: none (must be specified).

-l lang

Patch jar_or_dir_name with generated '*_lang.properties files'. Default: none (must be specified).

Other options are:

-v

Be verbose. Default: be quiet.

Case study: localizing XMLmind XML Editor

The reference language of XMLmind XML Editor (XXE) is English. This case study describes the localization of XXE in Spanish.

1. Extract all the English messages from xxe_app.jar and put the extracted messages into file en_es.msg (the name of this file is not significant).

   $ localize -x en_es.msg xxe_app.jar

   The extracted message file is always encoded using the native encoding of the platform. Therefore, you can type accented characters as usual.

2. Edit en_es.msg using a text editor and add a Spanish translation in each key= placeholder line.

                              . . . 
   styleSheetReloaded=Style sheet "{0}" reloaded.
   styleSheetReloaded=
   
   trimmingDocument=Stripping superfluous white space...
   trimmingDocument=
   
   undo=_Undo
   undo=
   
   untitled=Untitled
   untitled=
   
   userInput=User input
   userInput=
   
   viewClipboardContent=View Clipboard Content
   viewClipboardContent=
   
   window_menu=_Window
   window_menu=
   
   ----------com/xmlmind/xmleditapp/app/messages/Messages.properties
   ++++++++++com/xmlmind/xmleditapp/apt/messages/Messages.properties
   
   cancel=_Cancel
   cancel=
   
   defaultEncoding=_Default encoding:
   defaultEncoding=
                              . . . 

   Notes:

   • You don't need to translate all the sections. It is sufficient to translate:

     In xxe_app.jar:

     • com/xmlmind/xmleditapp/app/*.properties

     In xxe.jar (see step #5 below):

     • com/xmlmind/xmledit/command/*.properties
     • com/xmlmind/xmledit/dialog/*.properties
     • com/xmlmind/xmledit/edit/*.properties
     • com/xmlmind/xmledit/view/*.properties

     to localize the whole GUI of XXE.

     In fact, certain sections (for example, com/xmlmind/xmledit/xsd which deals with validation of XML Schema) are very, very hard to translate and its better not to translate them.

   • If you translate a section, all the messages must be translated otherwise a warning will be reported by localize. This warning signals the fact that some messages are missing and that the corresponding .properties file has not been created.
   • The translated message must be one-line long. The following escape sequences are recognized by the localize utility: \n (newline), \t (tab), \uXXXX (where XXXX is the code of a Unicode character in 4-digit hexadecimal notation).
   • The punctuation and capitalization of the original message must be respected.
   • Some messages contain one underscore character ('_') (see edit=_Edit in the figure above). Such messages are menu items and the underscore is located just before the letter which is used as the menu item mnemonic.

     Recommandations:

     • The location of the undescore depends on the language used for the menu item.

       For example: in english, Alt-F opens the File menu because the underscored letter is F (i.e. _File). In german, the File menu is called Datei and the underscored letter should be D (i.e. _Datei).

     • Do not underscore the same letter twice in the same GUI component (menu bar, menu, dialog box).
     • Because this constraint can be really tedious to check, it is better not to use this facility at all rather than not to use consistently. If you find underscoring menu mnemonics too tedious, do not underscore them at all.
   • A large number of messages contain strings {0}, {1}, {2}, etc. These are variables which are substituted by dynamically computed values just before the message is displayed to the user. The translated message must, of course, embed the same variables as the original message but the order of occurrence of the variables may be different if the syntax of the language requires so.

   Generating the same file for an already supported language may help you to better understand some of the messages.

   For example, if you understands French as well as English, this command will extract all English messages to file en_fr.msg, each English message being followed by the corresponding French message (if any):

   $ localize -x en_fr.msg -l2 fr xxe_app.jar

                              . . . 
   userInput=User input
   userInput=Action Utilisateur
   
   viewClipboardContent=View Clipboard Content
   viewClipboardContent=Afficher Contenu du Presse-Papier
   
   window_menu=_Window
   window_menu=Fenêtre
   
   ----------com/xmlmind/xmleditapp/app/messages/Messages.properties
   ++++++++++com/xmlmind/xmleditapp/apt/messages/Messages.properties
   
   cancel=_Cancel
   cancel=_Annuler
   
   defaultEncoding=_Default encoding:
   defaultEncoding=_Encodage par défaut:
                              . . . 

   This type of command must also be used if, for example, you have localized version 2.1 in spanish and want now to update your localization for version 2.2.

3. Apply the edited en_es.msg to xxe_app.jar:

   $ localize -p en_es.msg -l es xxe_app.jar
   $ ls
                              . . .
   xxe_app.jar
   xxe_app.jar.BAK

   Note the mandatory -l argument used to specify which .properties file are to be generated.

4. Run XXE to test your localization.

   Edit the shell script xxe on Unix (xxe.bat on Windows) and add -Duser.language=es in the java command line if the default locale of your desktop is not es.

5. Repeat the first 4 steps with xxe.jar instead of xxe_app.jar.