Chapter 9. Internationalization and Localization

After the description of Pentaho Reporting parameterization, functions and expressions, environment variables, and formulas, in this chapter you will learn everything about, internationalization and localization of a Pentaho report. This Pentaho Reporting capability will enable you to manage reports for the best multi-language support, without any dependency on a specific language or alphabet, instead, using a generic approach with labels for texts and strings and some properties to be used for their replacement.

This chapter is written as a reference manual for developers and information technologists. The goal is to share all the relevant and advanced features about internationalization and localization available in Pentaho Report Designer. After reading this chapter, you should feel comfortable with all the ways Pentaho Reporting can enable you to define reports in all the different languages you may need.

Internationalization and localization

As per every modern software, Pentaho Reporting is developed following all the best practices and patterns to support internationalization, so that it can be adapted to various languages, and regions without engineering changes.

Localization is the process of adapting internationalized software for a specific region or language by adding locale-specific components and translating text. Localization (which is potentially performed multiple times, for different locales) uses the infrastructure or flexibility provided by internationalization (which is ideally performed only once, or as an integral part of ongoing development).

Note

This description is mainly a quotation of the Wikipedia definition of internationalization and localization that you can find at https://en.wikipedia.org/wiki/Internationalization_and_localization. Even if the description is quite generic, it fits perfectly with Pentaho Reporting being developed as a standard (and modern) Java application...

Using resources to localize elements

In Pentaho Report Designer, there are three different elements available to be used for localization: resource-label, resource-field, and resource-message. All of them are available in the report element palette and can be used as usual-by dragging and dropping the element in the chosen place of the right band, directly in the report canvas.

The main idea behind the resource elements is that these kind of elements contain the key value for the resource and not directly the value to show. Once the key value is declared and used in a report element, a property file contains the association key/value and will be used at run time to show the final content to the user.

Using the resource-label element within your report allows you to localize labels with static texts. As introduced previously, this element contains the static resource key that will be resolved at runtime using the resource bundles detailed in the following paragraphs.

Using the resource-field...

Resources for localization

As introduced previously in the chapter, the localization of a Pentaho report requires some resources to resolve the keys declared in the report elements. Starting from the Report Designer user interface, you can access the resources from the upper menu, in File | Resources.... Once selected, the Resource Editor will appear as shown in the following screenshot:

In few words, the Resource Editor is nothing more and nothing less than a manager of property files. By default, it contains the default file (translations.properties), but you will soon learn how to add and remove other property files. The property files defined here are part of the Pentaho report and for this reason are stored directly in the .prpt file.

Using the buttons on the right, you can create, edit, remove, and even import/export property files. We will not detail the behavior of each button here, because it is supposed to be easy to understand, considering that it is nothing less and nothing more...

Testing the localization

After the correct setup of the localization of your Pentaho report, you may want to test it in all the possible languages and countries (in one word, called locale). To achieve that goal, Pentaho Report Designer can be configured to be used with one locale instead of another.

Starting from the Report Designer user interface, you can access the Pentaho Report Designer settings from the upper menu, in File | Configuration.... Once selected, the report configuration is shown as in the following screenshot.

In the core-module settings, you can recognize the .environment.designtime.Locale property, not defined with a default value. To set up the requested locale, check the property and fill the text field on the right, that will become editable. Then click the OK button and refresh the report to make the configuration active.

An example of report localization

To see how the localization works in practice, let's develop an example of localized Pentaho Report that you can use in your future tasks. The idea is to reuse a previous example, replacing some static labels with resource-label, and see how the report looks in a couple of different languages (we will use English and Spanish as examples).

For this purpose, let's reuse report_02.prpt we saw in Chapter 4, Creating a Report with Report Designer. If you followed the suggestion, you should have the report saved in your my_report folder in your development environment. If not, you can download it from the https://github.com/fcorti/pentaho-8-reporting-for-java-developers repository, from the Chapter 04 - Creating a report with Report Designer/my_reports path.

Once the report is opened in the Report Designer, select the label: Actuals per position title element in the Structure tab of the report explorer (you can find it under Master Report | Report Header). To replace...

Summary

In this chapter, you learnt everything about internationalization and localization using Pentaho Report Designer. You started with the definition of internationalization (and i18n) and then you saw what localization means in case of a Pentaho report. To make everything practical, you saw how to include resource elements (resource-label, resource-field, and resource-message) and how to resolve the content using the resource bundles. At last, you also saw how to test the various localizations for your Pentaho report.

To complete the description, for future reference, you also saw how to localize an existing report in English and Spanish (but other translations could be developed in the same way).

Now that you have read this chapter, you should feel comfortable with all the ways Pentaho Report Designer offers to manage internationalization and localization. This is an advanced task in developing complex Pentaho reports and makes you an expert in dealing with complex reports that can be...