Create and use translation files with BIRT

Hello everyone,

Today we are going to speak about report translation using BIRT.birt_logo
This task may become important as soon as you have multiple clients and you have to generate report in their own language. Most of the time, english is enough but sometimes you have to provide reports translated in other languages.

I will show you that it is quite simple to manage languages in BIRT reports but it can become quite a heavy job to maintain a lot of translations for lot of reports.

The translation is based on an essential element : the “.properties” file. This flat file contains a set of association between keys and values (“key=value”) corresponding to all the words and sentences that have to be translated. Here is an exemple of a “.properties” file containing the translation in EN/FR of welcome and bye :

“” :


“” :

bye=Au revoir

It is possible to organise translations in this file to manage them easily by combining keywords and dots “.” :

title.welcome = Bienvenu

A “properties” file has to be created for each language. All the files containing translations look like that :”” with xx_XX representing the language code. (exemple : the german code is de_DE)

I often use a default properties file, without suffix, ( containing the english version of translations. I associate this file to my report : by doing that, I’m sure that if none of the “.properties” file that I created correspond to the locale of the user, this “” will be used by default.

To link a translation file and all the translations available in other “.properties” file with the same name, go to the report properties. Go to “Resources”, in the “Properties Files” part, click on “Add files” and select the “” file.


You can link as many files as you want. Sometimes it can be interessant to split translations into many “properties” file regarding what they contain. For instance, a “” file may contain all the common translations ( units, metric system etc..). These translations will probably be usefull for lot of reports. For each report you will use this translation file and other specific ones.

Now that the translation file is linked to the report, you have to link the translations to the texts contained in the report. Regarding to the kind of text field, you may use different methods:

  • Labels

This field is the easiest field to translate. To translate it, click on the label and in its properties, click on “Localization”. Click on “Browse” to see all translations available in the translation(s) file(s) that you linked to the report. Select the correct value and click on “OK” .


If you correctly add you translation files to your report, the values in front of keys will be displayed in your BIRT locale. In my case, in French. This is possible only because I also have the “” file that has been automatically recognized. If this file did not exist, values in front of key would have been the ones in the “” file, so the english ones.

Remark : Quite the same translation method can be applied to link translation to “Map” properties : map_traduction

  • Custom text

When creating report, we often need to mix data and text. The custom text type of field can be used to do that. The translation of this field is a bit particular. This method can be used in “Text” ( html + dynamic text mode), “Data” or “Dynamic Text” field. Here is an exemple of a script not translated :

"Hello, today is the "

In this case, we have to translate “Hello, today is the”. To be able to do that, replace the “Hello, today is the” by :

reportContext.getMessage("welcometoday", reportContext.getLocale());

Of course, in my translation file, I have:

“” :

welcometoday=Welcome, today is the

“” :

welcometoday=Bienvenu, nous sommes le 
bye=Au revoir

To ease that kind of translation and not to have to write each time this script, you can create a javascript function that you call with the key in parameter. Put this javascript function in a “.js” and associate it to your report :

function translate(value){
 return reportContext.getMessage(value, reportContext.getLocale());

Using this function, the script will now look like that :

  • Externalised text

Finaly, the last method that you use to translate can be used each time you see the following icon :

externalised_TWe often meet this icon in graphs. Let’s take a simple exemple of a graph title that you want to translate. Click on the icon and check the “Externalised text” box. Select the translation in the list and click on “OK” :


It’s finished ! You can now translate all your reports using “properties” files.

In the next post, we will see which BIRT parameter to modify to be able to change locale and test report translation.

Tags: , , , , , , , , , , , , , , ,


  1. Hello. Question: My properties files are UTF-8 encoded. I am also using but when I render the report, the dates shown are corrupted? Any suggestions? Can I force encoding on the output?

    • Hi Anna,

      Do you have a simple report that you can send me and I can test ?
      When you say you render the report, is it locally on your Eclips-BIRT tool or using the BIRT Engine ?


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.