I’ve received a few questions asking how to localize BIRT reports. BIRT reports can be localized so that your users in offices around the world can see a report in their desired language and formating. BIRT can automatically take care of the number, date, and currency formatting but there are other parts of the report to consider that would normally consist of static text. These ncluding labels or text elements within a report, table and column headers, chart titles, etc. For these elements, we need to replace the static text with external text from a properties file.
To get started, I created a couple of .properties file. You will need one property file for each locale you plan to support. For our example, I created one called MyResources_us_EN.properties and MyResources_fr.properties. These are just text files and contain name value pairs like below.
welcome=Hello
goodbye=Later
…and…
welcome=Bonjour
goodbye=Au revoir
Once you have the properties files created, add them to your report project. You can now select one of the properties files in the Resource File property of the report design (screenshot below).
Now that the properties file has been set, you can assign ‘keys’ to various controls within the report. To add a key to a label, select the label and then Localization on the Property Editor tab.
Press the […] button and you can pick the key to use from a list
Perform these same steps for any other labels within the report. You can use external text within the chart as well, anywhere you see the following icon.
Pressing this button will invoke a list like below where you can pick the resource key to use.
If you need to externalize text that comes from a database, then you will need to use the mapping feature. For example, if I want to localize the text from a group header and I want to replace the office number (1 through 7) with the words “First Office” for English and “Premier Bureau” for French, then I start by selecting the Office Number data field. On the Map tab in the Property Editor, press the Add button to create a map rule.
In this example, when the Office Code field equals Office # 1, then replace the text with the value from our properties file that matches ‘1′. Create a unique mapping for each value you want to externalize.
Once you have created all your mappings and have assigned the keys to each label or chart, then you are ready to test that it all works. In order for the resource files to get selected correctly at runtime, we have to remove the locale specific information from the name of our resources file. You do this by selecting the whitespace on the report again, and then on the Resources tab. Remove ‘_us_EN’ from the name of the resource file so that it now reads ‘MyResources’ without any locale information at the end.
To test for different languages while in the BIRT Designer, select Window | Preferences | Report Design | Preview. I’ll select French since that was the only other locale that I have a properties file for.
Now when I run the report, my labels are replaced, the chart title is replaced, and the group header fields have been replaced.
If you are trying to set the name of the properties file or assign the resource keys with scripting, then you can do something like below in the beforeFactory event:
var rr = reportContext.getReportRunnable();
rr.designHandle.setProperty(”includeResource”, “MyResources”);
rr.getDesignInstance().getLabel(”GoodbyeLabel”).textKey = “goodbye”;
… or in the onPrepare event of a label control, you can use:
this.textKey = “welcome”;
If you are using the REAPI to set the location of the resource file… or assign keys, then you can use code similar to:
config.setResourcePath(”C:/work/eclipse/BIRT_221/resources”);
task.setLocale(ULocale.FRENCH);
IReportRunnable design = null;
ReportDesignHandle dh = null;
design = engine.openReportDesign(”C:/workspace_221/birt/Localization.rptdesign”);
dh = (ReportDesignHandle) design.getDesignHandle();
LabelHandle mylabel = (LabelHandle) dh.findElement(”LastLabel”);
mylabel.setTextKey(”welcome”);
All of these examples above can be downloaded from:
http://www.birt-exchange.com/modules/wfdownloads/singlefile.php?cid=2&lid=351
