Tools to translate .properties files (DRAFT)

Contents

Overview
Terminology
Overall procedures
Tools
Detail steps
mergetool: how to modify source files

Please see How to translate NetBeans IDE before this page. This page proposes the way to automate some part of translation work described at that page. This document describes the tools to translate resource bundles (Bundle.properties). The describing tools help to translate only new/updated messages, and help to format resource bundles to refer appropriate English messages.

Resource bundle:
NetBeans IDE uses .properties file as resource bundle. And all .properties files are named Bundle_${locale}.properties. ${locale} is locale strings (e.g. ja, zh_TW, zh, ko, ru, fr, ...). All strings in .properties file should be Unicode-encoded characters.

Unicode-encoded characters:
All strings in .properties files should be Unicode-encoded characters (\udddd notation) when it's used. native2ascii command in JDK converts from native code to Unicode-encoded characters. Only converted .properties file should be committed in cvs source tree. see native2ascii(1) for more detail.

Native Code:
The character code which you are using in your environment.

The following is overall procedures to create localized Bundle.properties.

1. Revert existing committed Bundle.properties from Unicode-encoded characters to Native code. (revert)
2. Merge the latest English messages with the translated messages
3. Translate newly added messages, or modified messages
4. Check the consistency of terminology
5. Convert from native code to Unicode-encoded characters. (convert)
6. Build localized jar file for testing, and test
7. commit tested Bundle_${locale}.properties

Apache Ant script
Ant script can automate some steps described at above. See build.xml described at below.

mergetool

This is a main tool proposed in this document.
All message can be identify by the three status of follows.

• New
  New message. It needs to be translate them from scratch by referring existing other translated messages.
• Modified
  Modified message. It has to be modified because base English message has been modified.
• Up-to-date
  Nothing has to be done.

When product or module is being updated, "New" and "Modified" messages need to be maintained. The purpose of mergetool is to identify the status of each messages, and to format message to translate easier. mergetool create the following file as an example. It's created by merging the latest English messages and the latest translated messages.

  1   # This is a sample Bundle.properties
  2   #
  3   
  4   # KEY_FOO=English Message Foo
  5   KEY_FOO=<translated Message Foo>
  6   
  7   # MODIFIED !!!
  8   # KEY_BAR=English Message Bar
 10   KEY_BAR=<translated Message Bar>
 11   
 12   # NEW !!!
 13   # KEY_YOYO=English Message Yoyo
 14   KEY_YOYO=English Message Yoyo

1. Read the latest English Bundle.properties, and copy English message as each message's comment. See line #4, #8, #13 in above example.
   The English message should be referred when translating, and to keep English message can help to maintain. So this mergetool leave all English messages as comments.
2. Search the message key (e.g. KEY_FOO) from the latest translated .properties file.
   • If the message key has been found with translated messages, put it. See line #5, #10 at above example. And check the translated .properties file if it has English message as comment.
     • If the English message exists as comment, compare English messages.
       • If the compared English messages are same, Status is Up-to-date. Nothing has to be done. See the message KEY_FOO in above example.
       • If the compared English messages are different. Status is Modified. The message needs to be updated. The flag "MODIFIED !!!" is added as comment. See the message KEY_BAR in above example.
     • If the English message does not exists as comment, copy existing translated message, and marked it as MODIFIED !!!.
   • If the message key has not been found with translated messages, the status is New. The message needs to be translated from scratch. mergetool adds the flag NEW !!! as comment. See the message KEY_YOYO in above example.

The following software is required. You may have all of them.

• JDK 1.4.x: The JDK1.4's method is used, so it works with only 1.4.x.
• Ant 1.4.1
• Ant 1.4.1 optional.jar

1. Checkout sources from cvs
   if you start the localization of 3.4, check out sources with tag release34.

   % cvs co -r 'release34' standard_nowww

2. Checkout .properties file to translate.

   % cvs co translatedfiles

   If your localized files has a tag, your can checkout by tag:

   % cvs co -r 'release34' translatedfiles

   As an example, the Japanese translated files has release34 tag. Please check it in cvs tree.
    
3. Checkout tools source files from cvs, it may be checked out already at the above steps. If there is not 'tools' directory under translatedfiles project, run checkout command at nb_all directory:

   % cvs co translatedfiles/tools

   You will see the following directory.

   	translatedfiles
     	    |- src
   	    |- src-todo
   	    |- tools
   	 	|----- build.xml
   		|----- translation-tools.jar
   		|----- translation-tools.mf
   		|----- mergetool.sh
   		|----- mergetool.bat
   		|----- src
   
   	

4. build tools by executing following ant command:

   % cd translatedfiles/tools
% ant tools

5. Edit the shell file and batch file
   UNIX:
   Open mergetool.sh, and edit as follows:

   before: installed_dir=nb_all/translatedfiles/tools
   after : installed_dir=<full_path_in_your_environment>/translatedfiles/tools

   Windows:
   Open mergetool.bat, and edit as follows:

   before: SET INST_DIR=nb_all\translatedfiles\tools
   after : SET INST_DIR=<full_path_in_your_environment>\translatedfiles\tools

6. UNIX: execution permission to mergetool.sh
7. Add 'tools' directory in your path environment
   UNIX (csh):

   % set path=<full_path_in_your_environment>/tools $path)

   Windows:
   Set via Control Panel, or type as follows in DOS prompt

   % set PATH=<full_path_in_your_environment>\tools;%PATH%

8. Go to tools directory, and edit build.xml for your language. In the build.xml, there is a line as follows:

   <property name="locale" value="ja"/>

   Please change value 'ja' to your locale before execution.
9. execute ant to build tools

   % cd tools
% ant clean

   Target 'clean' removes all files in 'src-todo' directory. Please save your files before execution
    
10. Revert .properties file in src directory from Unicode-encoded character to native code. The reverted files are located at src-todo directory.

    % ant revert

    All Bundle_${locale}.properties are reverted and located at src-todo directory. The reverted file name is Bundle_${locale}.native.prev. To convert only one module, set -Dmodule=<name> option. The following command revert .properties files in only 'text' module.

    % ant -Dmodule=text revert

11. Go to specific directory to confirm the reverted files. If you revert text

    % cd <src>translatedfiles/src-todo/text/src/org/netbeans/modules/text

    You will see the following two files.

    Bundle.properties: The latest English file
    Bundle_${locale}.native.prev: The latest translated file

12. At the reverted directory, execute mergetool.sh (UNIX) or mergetool.bat (Windows) to merge.

    % mergetool.sh Bundle.properties Bundle_${locale}.native.prev > Bundle_${locale}.native
% mergetool.bat Bundle.properties Bundle_${locale}.native.prev > Bundle_${locale}.native

    Please be sure to add redirect option '>'. And the redirected file name must be Bundle_${locale}.native.
13. Open Bundle_${locale}.native.

    "NEW !!!" indicates the message needs to be translated
    "MODIFIED !!!" indicates the message needs to be updated

14. By referring the English message which is commented out, you can update the translated messages, or you can translate.

    NOTE:
    Even if your existing translated files don't have English message as comment, "NEW !!!" status is marked correctly, so you can use this flag to indicate new messages. But If your existing translated files does not have English messages as comment, all existing messages are maked as "MODIFIED !!!", so you need verify messages by using cvs diff command (or other tool) to English Bundle.properties.

15. Remove "NEW !!!", and "MODIFIED !!!" when editing has been finished.
16. When all files have been updated or translated, go to tools directory, and convert .properties files to Unicode-encoded characters.

    % ant convert

    To convert only one module, set -Dmodule=<name> option. The following command revert .properties files in only text module. Bundle_${locale}.properties files are created in translatedfiles/src directory.

    % ant -Dmodule=text convert

17. You can test, and commit tested .properties files. You should not commit any files under src-todo directory.

	      translatedfiles
		 |---- src
		 |---- src-todo
		 |---- tools
			 |---- build.xml
			 |---- src
				|-----org
				       |----netbeans
			       	     	...