Introduction

[Now you can have your Pentaho 5+ installation in your favourite language!]()

The pentahoLanguagePacks project is a Pentaho plugin that allows a system administrator to install any localised version of the user interface of the Pentaho Business Intelligence server.

This project contains:

• an application, the Pentaho Language Pack Installer;
• all sets of localised messages (one folder per locale)

Whenever a given localisation reaches a state in which it becomes usable, trimmed versions of the installer are released to the Pentaho Marketplace, containing only the files relevant to that locale.

If you are only interested in installing an existing language pack, then you should simply download it from the marketplace. The instructions that follow are mainly directed to developers and translators.

Disclaimer

The language pack installers work by massively copying files to your Pentaho installation, eventually overwriting and patching existing files in your installation.

If you upgrade some plugin (using the marketplace, for instance), you may need to run the language pack installer again in order to patch your installation with the localisation files.

We heavily recommend that you test the installer in a dedicated BI server before using this installer in a production setting. Please backup both your server and your solution!

Contributing with a translation

This application allows you to contribute incrementally to any localisation of your choosing. You just need to:

1. install the application
2. translate the files on the data/ folder
3. test your work
4. send your work back to us

You don't have to do all the work at once: you can do as many iterations as you want!

1. Install the application

Satisfy the dependencies

The Language Pack Installer requires Pentaho 5+, and depends on the following CTools:

• CDF: Community Dashboard Framework
• CDE: Community Dashboard Editor

You can install these packages from the Pentaho Marketplace, or manually download them from Pentaho's Continuous Integration server and unzip the .zip file to your pentaho-solutions/system folder.

If you are using the Enterprise Edition, we recommend you to install the Pentaho Marketplace. Follow the instructions at Pedro Alves's blog.

Download the plugin

There are basically two ways to get the plugin/application:

1. You can download a zip file from github:

   • unzip the file and rename the folder to languagePackInstaller
   • move/copy the languagePackInstaller folder to your pentaho-solutions/system.

2. Alternatively, you can clone the git repository hosted on github:

   • open a terminal and go to your pentaho-solutions/system folder
   • git clone git@github.com:webdetails/pentahoLanguagePacks.git languagePackInstaller

The plugin is shipped without the java libraries. To get them, you will need to go to the command line. In the pentaho-solutions/system/languagePackInstaller folder, run ant resolve. If your system does not have the ant utility, download it from Apache ant.

Don't forget that the plugin will only be loaded (and thus be available) at the next restart of the BI server.

2. Translate the files

You just need to edit the files under data/${languageCode}, where ${languageCode} stands for the language code (e.g. fr, pt_PT).

If the language of your choice is not available, create an issue in our bug tracker and we will generate the pack for you. Take a look at the Appendix 1 for the currently supported locales.

Even though we don't recommend it, you can try to generate the file bundle. yourself: the script tools/generate-language.sh can be used to generate a language pack from scratch, i.e. from the original messages in English. It works by copying the default tokens and appending a <TRANSLATE ME> to each string. The script tries to recycle any existing items already on your installation. Currently you will need to manually edit the file to get it to work on your system.

Concerning the translation process, please observe the following notes:

1. Please save all files using UTF8 encoding.

2. Do not bother to edit the supported_languages.properties files. Their contents will be ignored by the language pack installer.

3. Go through all the files.

4. While editing the file data/${languageCode}/metadata.json, ensure the fields languageCode and language are consistent with your modifications. You should also edit the maintainer, credits and/or sponsors entries to ensure the work is properly credited and you get the public recognition (and gratitude) for your work.

5. Future versions of the language pack installers will be localised. If you are working on the language code XX, it would be nice if you went through all data/${languageCode}/resources/lang/ folders and added a file messages_XX.properties.

3. Test your work

If you login as admin, you'll see an item under the Tools menu.
You can also use the direct REST call. Assuming you are working in your local machine, the URL is : http://localhost:8080/pentaho/plugin/languagePackInstaller/api/main

The installer works by installing whatever language is specified in the data/metadata.json file. By default, the field languageCode is set to tlh, which is the language code for the Klingon language, an artificial language familiar to those who watched Star Trek. We didn't bother to translate Pentaho into Klingon, however you if you submit a contribution, we will merge it!

Typically, if you are working on the data/${languageCode} folder, you should edit the file data/${languageCode}/metadata.json and copy its contents to data/metadata.json.

Needless to say: you will need to run the plugin every time you want to patch your Pentaho server with the localised version.

Even though we don't recommend it, you can also generate the individual, locale-specific language packs. These plugins are obtained by cloning the plugin, stripping the data folder to the bare minimum and performing some other tasks such as character escaping. We already automated the process: run ant -DlangCode=pt_PT clean resolve build-language-pack (replace pt_PT with the appropriate language code). You will see that the folder bin/languagePack_pt_PT was created.

Common issues

1. In the particular case of the automatically generated files biserver/tomcat/webapps/pentaho/mantle/mantleMessages_*.properties, the symbols < and > can break the Pentaho User Console, yielding an error Error generating XUL: Failed to parse: <?xml version="1.0" encoding="UTF-8"?>. This error disappears as soon as these symbols are eliminated.

4. Send your work back to us

As soon as you are done with a major block of work, you should send us your work so that it is shared with the rest of the Pentaho community. If you remembered to increase the entry version in the file data/${languageCode}/metadata.json, the Pentaho Marketplace will notify the users that an update is available.

If you don't know what git is, just zip the whole plugin and send it back to us. We will merge it at the earliest opportunity.

However, merging your changes is much easier for us if you provide us a git repository. If you are willing to go through this, do the following:

1. create a github account (unless you already have one)
2. create a fork of the Webdetails repository https://github.com/webdetails/pentahoLanguagePacks.
3. open a command line and type:
   • cd pentaho-solutions/system/languagePackInstaller
   • git remote add my_fork git@github.com:${username}/pentahoLanguagePacks.git (replace ${username} with your github user name)
4. Do your stuff and commit the work locally.
5. Whenever you want, push your changes to your fork on github (e.g. git push my_fork master).
6. When you feel like we should merge your changes, visit your github account and issue a pull request. Please include your language code in the title of the request, e.g.:
   • [pt_PT] translated tomcat/ folder

Appendix 1: Available locales

The following is a list of the locales that Pentaho recognises. This list accounts for country-specific translations. If the translation is valid for all cases, the suffix is dropped. For instance, if you requested the Netherlands variation of Dutch (code nl_NL), Pentaho will look for entries using the following order: nl_NL -> nl -> (default english message).