Jenkins : Translation Tool

Created by Unknown User (manuel_carrasco), last modified by Unknown User (manolo) on May 24, 2012

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 wording, but also because normally there are not good tools to help enough.

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

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

Basis

- Jenkins uses three ways to internationalize elements:

  1. For texts used directly in .java classes, it uses 'Message.properties' files which contains a collection of 'key=value' lines in English. In this case you have to:
    1. Create the  file Message_xx.properties copying the original file (xx means your language code)
    2. Edit it, and replace the values for the appropriate text in your language.
  2. Jenkins uses files with the '.jelly' extension for html template files. Once you have locate these files you have to:
    1. Identify all the keys being used in the nnnnn.jelly file
    2. Create the file nnnnn_xx.properties
    3. Add all the keys found to the new file and set the translated values.
  3. Finally there are a large amount of '.html' files used normally for help tips in the application. Find this files and:
    1. Copy the file with the name nnnnn_xx.html
    2. Edit and translate it

- Jenkins only supports files encoded with ISO-8859-1 or ASCII, so after modifying the files be sure to convert them to the correct charset.

- 'translation-tool.pl' has been coded in 'perl'.

  • 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 analyzes them to extract the keys used in the application. 
  • By default (without parameters) the script writes a report to the screen with the keys which are missing, orphans, 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-8859-1, 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 Jenkins trunk. So to execute it you have either to put it in your 'PATH', or add the folder before the command.
  • Execute the script without arguments to get the usage message: 
    ~/home/workspace/jenkins$ main/translation-tool.pl --help

Translation Tool for Jenknis

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 Jenkins internationalization. 
    ~/home/workspace/jenkins$ main/translation-tool.pl --lang=es main

File: ./maven-plugin/src/main/resources/jenkins/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/jenkins/plugins/postbuild-task$ ../../main/translation-tool.pl --lang=es \
   --reuse=../.. --add --remove --editor=gedit --toiso


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

Converting file ./src/main/resources/jenkins/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/jenkins/plugins/sonar$ ../../main/translation-tool.pl --lang=es \
   --add --remove --editor=gedit --toiso

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

File: ./src/main/resources/jenkins/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%)