Skip to main content
Pentaho Documentation

Localization

This section explains how to localize all Pentaho applications. There are two main paradigms for internationalization: programs that abstract their integrated textual content to unified message bundles, and programs that store text in individual properties files inside of JARs.

Design Tool Localization

All of Pentaho's design tools can be translated to the extent that their text strings are abstracted to properties files. There are already a number of localized message bundles in some design tools (PDI in particular), though they may be incomplete.

The basic process for translating message bundles is to search for messages.properties files and create localized versions of them, following the standard Java localization naming convention as explained in Use the Kettle Translator.

Once you have found the JARs containing the message bundles, create overrides for them by creating a translations directory and unpacking the messages.properties files from the JARs into it:

mkdir translation
cd translation
unzip ./lib/*.jar '*.properties'

Then add that directory to the classpath by editing launcher.properties, and edit or create a localized message bundle for each properties file you extracted.

The quickest and easiest ways to locate the appropriate JARs, add override directories, and create message bundles is explained for each design tool in the below sections.

Design Tool File Path and File Name Details
Aggregation Designer /aggregation-designer/lib/pentaho-*.jar

Modified launcher.properties classpath: classpath=../translations:log4j.xml

Pentaho Data Integration (Kettle) /data-integration/lib/kettle-*.jar

launcher.properties classpath prefix: classpath=../translations:

Note: The Kettle project has a translator tool to help facilitate large-scale localization efforts. To get it, check out the Kettle source code and run translator.sh or Translator.bat and either check in the changes, or zip them and email the archive to a committer. See Use the Kettle Translator for more information.

Metadata Editor

/metadata-editor/lib/pentaho-metadata-editor*.jar

/metadata-editor/libext/pentaho/pentaho-*.jar

Edit the metadata-editor (.sh or .bat) script, and modify the CLASSPATH variable accordingly:

CLASSPATH=./translations:
Report Designer

/report-designer/lib/pentaho-reporting-*.jar

/report-designer/lib/report-design*.jar

launcher.properties classpath prefix: classpath=translations:
Schema Workbench

/schema-workbench/lib/workbench.jar

/schema-workbench/lib/mondrian.jar

Edit the workbench (.sh or .bat) script, and locate the following line: CP="${MONDRIAN_HOME}/lib/commons-collections.jar". Now create a new line directly below it and paste this in:

CP="${CP}${PS}${MONDRIAN_HOME}/translations"
Pentaho Server /pentaho-server/tomcat/webapps/pentaho/WEB-INF/lib/pentaho-bi-platform-*.jar

This process is described in much more detail in Pentaho Server and Thin Client Message Bundles. However, if you're following the same abbreviated procedure as above, here are the basics (minus the thin client plugins):

Search for:

Path to use as a classpath override (you don't have to declare it): /pentaho-server/tomcat/webapps/pentaho/WEB-INF/classes/

Use the Kettle Translator

This procedure involves downloading and compiling source code. The program you build will not be covered by standard Pentaho support agreements. If you want to translate message bundles without compiling from source, you can simply search for messages_en_US.properties files within the data-integration-client directory (including all of the JARs therein). Properties files can be inserted into JARs without invalidating your support agreement; you can also override those JARs with directories in the PDI classpath.

Pentaho Data Integration has thousands of translatable strings. Because there are so many, and the number of strings increases with each new step and entry, Pentaho provides a graphical translation tool to make the process easier.

Before commencing a translation project, check to make sure the target language isn't already available. PDI already has complete or partially-complete translations for the following locales:

  • en_US
  • it_IT
  • fr_FR
  • ja_JP
  • es_AR
  • ko_KR
  • zh_CN
  • de_DE
  • es_ES
  • pt_BR
  • nl_NL
  • pt_PT

Additionally, there are certain translation rules and guidelines for some languages. You may need to search for the current rules and guidelines for the language you are using.

To use the translation tool, follow the below directions.

  1. Check out the PDI source code for the release you are creating localized message bundles for. The project root is: https://github.com/pentaho/pentaho-kettle.
  2. Run the translator tool (Translator.bat on Windows; translator.sh on Linux) in the root directory of the PDI source code that you checked out. The translator GUI will come up.
  3. In the upper left pane, select (or create) the locale to translate into.
  4. In the large left pane, select the package name to work on. Packages are color coded. Light grey means there are between 1 and 5 missing keys; dark grey means there are 6-10; yellow means 11-25; orange means 26-50; and red packages have more than 50 keys that are missing translations for the selected locale. Once you select a package, the translatable keys list will populate.
  5. Select a key from the Todo list: pane in the middle of the window.
  6. Type in the translated text in the Translation: pane on the right, then click Apply.
  7. When you've completed your translation effort, click Save.
  8. If you intend to contribute your translations back to the Kettle project, you can commit them back to the source tree, or you can click the Zip button in the translator interface to collect all of the new translated message files into a single zip archive.

    Pentaho Data Integration is open source software, and represents the contributions of many people. The project maintainers ask that you contribute back any localized message bundles that you create.

  9. In order to use PDI with these translated messages, you must recompile it from the source you checked out.
    ant -f build.xml clean targz
    

If you've translated all of the available keys, then PDI should be entirely localized for your target language. Any untranslated keys will fall back to its superset language (messages_fr_FR.properties will fall back to messages_FR.properties), and as a last resort, to messages_en_US.properties.