Translation Tool

Introduction

Translate an application is a hard work, not only because you have to know what the software does and what the developer means with each text, but also because normally there are not tools to help enough.

'translation-tool.pl' is a simple an useful command-line tool to help translators of Hudson and its plugins.

Please, take a look to Hudson Internationalization page to understand and get a better explanation about Internationalization in Hudson

Basis

- Hudson uses three ways to internationalize elements:

For texts used directly in .java classes, it uses 'Message.properties' files which have the set of 'key=value' in English. In this cases you have to:
1. Create the file Message_xx.properties copying the original file in English (xx means your language code)
2. Edit it and change the values for your language.
Hudson uses files with the 'nnnnn.jelly' extension for html templates (nnnnn means any name). These files use the keys rounding them with especial characters. Once you have locate these files you have to:
1. Create the file nnnnn_xx.properties
2. Identify all the keys being used in nnnnn.jelly
3. Add all the keys found to the new file and put the translated values.
There are a large amount of nnnnn.html files used normally for help tips in the application. Look for this files and do:
1. Copy the file with the name nnnnn_xx.html
2. Edit and translate it

- Hudson only supports files encoded with ISO-8859 or ASCII, so after doing your modifications be sore to convert them to the correct charset.

- The tool is coded in 'perl', so you need it installed it in your system.

Perl is installed by default in any unix flavour (linux, freebsd, opensolaris, etc),
In Windows you have to install it (from ActiveState or Cygwin) and call the script adding the interpreter to the command line.

How translation-tool.pl helps us to translate

It recursively looks for translatable files in a folder, and analizes them to extract the keys being used in the application.
By default (without parameters) the script writes a report to the screen with the keys which are missing, orphand, empty, or which have the same value than in English
Adding the parameter '--add', the script generates the appropriate files and adds missing keys to them, or updates the files if they already exist. The script put the value of the keys in English as a reference.
Adding the parameter '--editor=editor' the script will call the command 'editor' for each file which have untranslated keys.
Passing the parameter '--remove' the script will remove orphan keys which are not in use.
Finally the script is able to convert UTF-8 files to ISO-8957, or to ASCII with the java unicode representation '\uXXX' for non-ascii characteres.

Execution and Syntax

The tool is placed in the folder 'main' of the Hudson trunk. So to execute it you have either to put it in your classpath, or add the path before the comand.

Execute the script without arguments to get the usage message:

~/home/workspace/hudson$ /main/translation-tool.pl --help

Translation Tool for Hudson

Usage: main/translation-tool.pl --lang=xx [options] [dir]

   dir:                   -> source folder for searching files (default current)
   options:
     --lang=xx            -> language code to use (it is mandatory and it has to be different to English)
     --toiso=true|false   -> convert files in UTF-8 to ISO-8859 (default false)
     --toascii=true|false -> convert files in UTF-8 to ASCII using the native2ascii command (default false)
     --add=true|false     -> generate new files and add new keys to existing files (default false)
     --remove=true|false  -> remove unused key/value pair for existing files (default false)
     --editor=command     -> command to run over each updated file, implies add=true (default none)
     --reuse=folder       -> load a cache with keys already translated in the folder provided in
                             order to utilize them when the same key appears

   Examples:
     - Look for Spanish files with incomplete keys in the 'main' folder,
       edit them with gedit, and finally convert them to ISO-8859
        main/translation-tool.pl --lang=es --editor=gedit --toiso main
     - Convert all Japanese files in the current folder encoded with UTF-8 to ASCII
        main/translation-tool.pl --lang=ja --toascii .
     - Remove all orphand keys from German files which are in the current file
        main/translation-tool.pl --lang=de --remove .

Show a report about the status of Spanish Hudson internationalization.

~/home/workspace/hudson$ main/translation-tool.pl --lang=es main

File: ./maven-plugin/src/main/resources/hudson/maven/Messages_es.properties
  Missing -> MavenModuleSetBuild.DiscoveredModule
  Empty   -> MavenModuleSet.DiplayName
  Unused  -> MavenModule.Name
  Same    -> MavenModule.Pronoun

TOTAL: Files: 527 Keys: 1502 Done: 1498(99.73%)
       Missing: 1(0.07%) Orphan: 1(0.07%) Empty: 1(0.07%) Same: 1(0.07%)

And here is where the script comes really useful: I want to translate the plugin 'postbuildtask' to Spanish and the script does:

Generate new files with all keys to translate.
Translate automatically the keys which already exist in other files in the project.
Edit each new file using gnome text editor (gedit), so that the user can translate the keys.

Convert the files to ISO, after the user saves them.

~/home/workspace/hudson/plugins/postbuild-task$ ../../main/translation-tool.pl --lang=es \
   --reuse=../.. --add --remove --editor=gedit --toiso


File: ./src/main/resources/hudson/plugins/postbuildtask/PostbuildTask/config_es.properties
  Adding  -> Tasks
  Adding  -> Log\ text
  Adding  -> Delete\ task
  Adding  -> Script
  Adding  -> Operation

Converting file ./src/main/resources/hudson/plugins/postbuildtask/PostbuildTask/config_es.properties to ISO-8859

TOTAL: Files: 2 Keys: 5 Done: 0(0.00%)
       Missing: 5(100.00%) Orphan: 0(0.00%) Empty: 0(0.00%) Same: 0(0.00%)

You can use the script to edit missing keys in already translated files

 ~/home/workspace/hudson/plugins/sonar$ ../../main/translation-tool.pl --lang=es \
   --add --remove --editor=gedit --toiso

File: ./src/main/resources/hudson/plugins/sonar/Messages_es.properties
  Same    -> SonarAction.Sonar

File: ./src/main/resources/hudson/plugins/sonar/SonarPublisher/config_es.properties
  Empty   -> SonarInstallation.error

TOTAL: Files: 6 Keys: 75 Done: 73(97.33%)
       Missing: 0(0.00%) Orphan: 0(0.00%) Empty: 1(1.33%) Same: 1(1.33%)

Translation Tool

Introduction

Basis

How translation-tool.pl helps us to translate

Execution and Syntax

Labels: