Maybe you have already read the official documentation page Localize a report or the Hitachi's blog post Internationalization and localization of Pentaho Report Designer. Yet, you may still be unsure about the real possibilities of how to localize your Pentaho Reporting Designer reports. You can take this article as an addendum to the linked resources that will hopefully spare you some time on investigating the missing pieces of this functionality, including possible gotchas of the Designer.
Note: The localization functions were tested with version 9.1 of the Pentaho Report Designer and Pentaho Server.
The basic principles
Firstly, let me shortly recapitulate how localization is done in the Designer:
- The localization is based on the Java's well-known "Resource bundles" mechanism, where you store your translated texts in one or more .properties files. Every such file basically holds a list of "key-value" string pairs. Designer authors call them "resources" in general. In the case of Designer, these files may also be stored as a part of your report (.prpt ZIP file) - I reference them as "inner resources" below.
- When you want to have a text localized, i. e. automatically translated into the language used by the user of your report, you need to add one of these fields into your report: Resource Message, Resource Label, or Resource Field. Then, in the field's attribute called value, you enter the "key" matching a key from one of your resources. You can also, but do not have to, specify the resource-identifier attribute in order to use a concrete resource - we'll get to this in detail later on.
How can I name my resources within a report?
Well, while Designer lets you name your inner resources whatever you like, naming your resource other than "<resource-name>.properties" will just not work. This is caused by the fact that every resource is stored as a file and it is expected that it will have the .properties extension - but Designer doesn't automatically append this extension for you when storing an inner resource!
Be careful that even when you import a resource from an external file, Designer expects you to fill in the correct name of your new inner resource all by yourself. Moreover, renaming an inner resource is not supported.
As you can see, using inner resources can be quite tricky.
Is there a default resource for a report?
The answer is YES, the default resource is named translations. This means that when you don't fill in the resource-identifier attribute of a resource field, Designer looks for a text in the resource file named "translations.properties" (or in whatever language variant of that file, of course).
Oddly enough, there is not a single word on this in the official documentation, but it is mentioned in the blog post linked above. Finally, it looks like there is no way of how to change this default resource name on any level.
Where can I store my resources?
There are quite a few locations where Designer looks for the resource files. The files are looked up in the following locations, in order:
- Inner resources stored within the report.
- The same directory where the report file is stored. (Strangely enough, this doesn't seem to be documented.)
- Directory "[Designer Install]/resources", or "pentaho/WEB-INF/classes" in the case of deploying reports to a Pentaho Server. This is told to be a good location for resources shared among reports. I cannot quite imagine though that common report makers will get access to this Pentaho system folder.
We may say that the closer the resource file is to the report, the higher priority it gets.
What if I've got accents in my texts?
Whenever there is a character in your text that is outside the Latin-1 (ISO-8859-1) charset, it must be entered by using a Unicode escape sequence, e. g. "\u00A0" for the gold old non-breaking space character. There is no built-in support for easily editing these characters within the Designer's Resource Editor, which might be another reason for keeping your resources rather as external files.
We may expect there will be a support for storing texts in UTF-8 in the future, so that editing resources gets easier.
Conclusion
As you can see, Pentaho Report Designer offers quite a lot of possibilities when it comes to localizing reports. But there is also some undocumented stuff and some gotchas that I tried to make you aware of, hopefully successfully. :) I will be glad if you share your own experience and findings in the comments. Are they the same, or do you find some differences? I think it would also be cool to have a comparison with how localization is done in the competitive JasperReports solution...
