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 as standalone plugin zips (one per locale).

If you are only interested in installing an existing language pack, then you should install it via the Pentaho Plugin Manager or download a pre-built zip from the releases page. 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, 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!

Pre-requisites for building the project

• Maven, version 3.6+
• Java JDK 17+
• This settings.xml in your <user-home>/.m2 directory

Building it

mvn clean package

The plugin zip will be generated in assemblies/pentaho-plugin/target/.

Building a standalone language pack for a specific locale

mvn clean package -DlangCode=pt_PT

This produces a standalone languagePack_pt_PT installer zip in assemblies/pentaho-plugin/target/dist/.

Building all language packs

mvn clean package -Pbuild-all-language-packs

This iterates over all locales in data/ (excluding en) and produces one zip per locale.

Running validation tests

mvn test -pl assemblies/pentaho-plugin

This validates all locale metadata, directory structure, and required files across all 43+ locales.

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 11.0+, and depends on the following CTools:

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

You can install these packages via the Pentaho Plugin Manager.

Download the plugin

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

1. Build from source (recommended for developers):

   • Clone the git repository: git clone git@github.com:webdetails/pentahoLanguagePacks.git
   • Build: mvn clean package
   • Unzip assemblies/pentaho-plugin/target/language-pack-installer-pentaho-plugin-*.zip to your pentaho-solutions/system/ folder

2. Download from GitHub releases:

   • Download the zip from the releases page
   • Unzip and rename the folder to languagePackInstaller
   • Move/copy to your pentaho-solutions/system/

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 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 localized version.

Even though we don't recommend it, you can also generate the individual, locale-specific language packs:

mvn clean package -DlangCode=pt_PT

(Replace pt_PT with the appropriate language code.) The generated pack will appear in assemblies/pentaho-plugin/target/dist/.

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 update will be available in the next plugin release.

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).

Language	Country	Locale ID
Albanian	Albania	sq_AL
Arabic	Algeria	ar_DZ
Arabic	Bahrain	ar_BH
Arabic	Egypt	ar_EG
Arabic	Iraq	ar_IQ
Arabic	Jordan	ar_JO
Arabic	Kuwait	ar_KW
Arabic	Lebanon	ar_LB
Arabic	Libya	ar_LY
Arabic	Morocco	ar_MA
Arabic	Oman	ar_OM
Arabic	Qatar	ar_QA
Arabic	Saudi Arabia	ar_SA
Arabic	Sudan	ar_SD
Arabic	Syria	ar_SY
Arabic	Tunisia	ar_TN
Arabic	United Arab Emirates	ar_AE
Arabic	Yemen	ar_YE
Belarusian	Belarus	be_BY
Bulgarian	Bulgaria	bg_BG
Catalan	Spain	ca_ES
Chinese (Simplified)	China	zh_CN
Chinese (Simplified)	Singapore	zh_SG
Chinese (Traditional)	Hong Kong	zh_HK
Chinese (Traditional)	Taiwan	zh_TW
Croatian	Croatia	hr_HR
Czech	Czech Republic	cs_CZ
Danish	Denmark	da_DK
Dutch	Belgium	nl_BE
Dutch	Netherlands	nl_NL
English	Australia	en_AU
English	Canada	en_CA
English	India	en_IN
English	Ireland	en_IE
English	Malta	en_MT
English	New Zealand	en_NZ
English	Philippines	en_PH
English	Singapore	en_SG
English	South Africa	en_ZA
English	United Kingdom	en_GB
English	United States	en_US
Estonian	Estonia	et_EE
Finnish	Finland	fi_FI
French	Belgium	fr_BE
French	Canada	fr_CA
French	France	fr_FR
French	Luxembourg	fr_LU
French	Switzerland	fr_CH
German	Austria	de_AT
German	Germany	de_DE
German	Luxembourg	de_LU
German	Switzerland	de_CH
Greek	Cyprus	el_CY
Greek	Greece	el_GR
Hebrew	Israel	iw_IL
Hindi	India	hi_IN
Hungarian	Hungary	hu_HU
Icelandic	Iceland	is_IS
Indonesian	Indonesia	in_ID
Irish	Ireland	ga_IE
Italian	Italy	it_IT
Italian	Switzerland	it_CH
Japanese (Gregorian calendar)	Japan	ja_JP
Japanese (Imperial calendar)	Japan	ja_JP_JP
Korean	South Korea	ko_KR
Latvian	Latvia	lv_LV
Lithuanian	Lithuania	lt_LT
Macedonian	Macedonia	mk_MK
Malay	Malaysia	ms_MY
Maltese	Malta	mt_MT
Norwegian (Bokmål)	Norway	no_NO
Norwegian (Nynorsk)	Norway	no_NO_NY
Polish	Poland	pl_PL
Portuguese	Brazil	pt_BR
Portuguese	Portugal	pt_PT
Romanian	Romania	ro_RO
Russian	Russia	ru_RU
Serbian (Cyrillic)	Bosnia and Herzegovina	sr_BA
Serbian (Cyrillic)	Montenegro	sr_ME
Serbian (Cyrillic)	Serbia	sr_RS
Serbian (Latin)	Bosnia and Herzegovina	sr_Latn_BA
Serbian (Latin)	Montenegro	sr_Latn_ME
Serbian (Latin)	Serbia	sr_Latn_RS
Slovak	Slovakia	sk_SK
Slovenian	Slovenia	sl_SI
Spanish	Argentina	es_AR
Spanish	Bolivia	es_BO
Spanish	Chile	es_CL
Spanish	Colombia	es_CO
Spanish	Costa Rica	es_CR
Spanish	Dominican Republic	es_DO
Spanish	Ecuador	es_EC
Spanish	El Salvador	es_SV
Spanish	Guatemala	es_GT
Spanish	Honduras	es_HN
Spanish	Mexico	es_MX
Spanish	Nicaragua	es_NI
Spanish	Panama	es_PA
Spanish	Paraguay	es_PY
Spanish	Peru	es_PE
Spanish	Puerto Rico	es_PR
Spanish	Spain	es_ES
Spanish	United States	es_US
Spanish	Uruguay	es_UY
Spanish	Venezuela	es_VE
Swedish	Sweden	sv_SE
Thai (Western digits)	Thailand	th_TH
Thai (Thai digits)	Thailand	th_TH_TH
Turkish	Turkey	tr_TR
Ukrainian	Ukraine	uk_UA
Vietnamese	Vietnam	vi_VN