Localizing BIRT Reports with report parameters

rmurphy

The report generation process consists of two phases. Generation and presentation. During the generation phase, report parameters are used to filter data, alter the physical report, etc. The generation phase accesses the data and uses the parameters to produce an instance of the report known as a report document (rptdocument). The second phase, which can occur immediately after the generation phase or at a later date by reading in a rptdocument, is responsible for taking the report document and applying localization and rendering the report to the desired output format. This separation of tasks allows you to generate a single report and subsequently render the report to a multitude of users in different locales and in different output formats.<br />
<br />
Typical localization occurs during the presentation phase and uses the localization text key property of report elements that can be localized. Since report parameters are used during the generation phase, a report parameter will typically not have any effect on localization of a report. However BIRT is a very flexible tool and because of this, you can use most of the localization infrastructure and some report scripting to prompt users for a desired locale for which the report should be generated.<br />
<br />
The report design attached to this post uses both methods of localization. The top two labels in the report design use the "typical" localization approach. These labels have the text key set for the localization property and therefore will be localized during the presentation phase based on the user's locale, or the __locale URL parameter. The header labels in the table are localized using Javascript in the onCreate method of the data element. This script uses the locale set in the "lc" variable (which is set in the report's beforeFactory method) to get the localized message from the reportContext. And lastly, the display office code uses script directly in the binding of the data element to get localized text and display it based on the value of the OFFICECODE.<br />
<br />
You cannot use both methods of localization on an individual report item. If the text key is set on the localization property, this will always take priority.<br />
<br />
When running the attached design, you will see that when you select a particular locale via the report parameter, the table header row and DisplayOfficeCode will be localized. Only when you use the __locale URL parameter (or set your preview locale in the BIRT Report Designer) will you see the top two labels be localized. Keep in mind that the __locale URL parameter will not have any effect on the table header row or the DisplayOfficeCode since it is not localized using the localization property of the report item.<br />
<br />
In order to run this example, you will need to make the two properties files available to the BIRT engine by placing them in the resources folder. If you want to view this in the BIRT Report Designer, the project folder is automatically included as part of the resource path. To switch the locale of the viewer to affect localization with the text key, go to Window --> Preferences --> Report Design --> Preview, and then select your desired locale. The attached report design is based on BIRT 2.3.2.