Sample Reference - Schema Reference - Configuration Reference - API (Javadoc)
|
|
|
|
JasperReports - I18n Sample (version 3.7.6) | ![]() |
|
|
|
Main Features in This Sample | |
| Internationalized Report Templates |
![]() | ![]() | ![]() | ![]() |
|
|
top | |||||
|
|||||
![]() | Internationalized Report Templates | Documented by Sanda Zaharia | |||
|
|||||
| Description / Goal |
| How to generate reports in different languages using internationalization support. | ||
| Since |
| 0.6.2 | ||
|
|||||
|
Internationalization Overview
JasperReports lets you associate a java.util.ResourceBundle with the report
template, either at design time (by using the resourceBundle attribute) or at
runtime (by providing a value for the built-in REPORT_RESOURCE_BUNDLE parameter).
If the report needs to be generated in a locale that is different from the current one,
the built-in REPORT_LOCALE parameter can be used to specify the runtime locale when filling the
report.
To facilitate report internationalization, a special syntax is available inside report expressions to reference java.lang.String resources placed inside a
java.util.ResourceBundle object associated with the report. The $R{} syntax is for
wrapping resource bundle keys to retrieve the value for that key.
For formatting messages in different languages based on the report locale, a built-in method inside the report’s JRCalculator offers functionality similar to the java.text.MessageFormat class. This method,
msg() , has three convenient signatures that allow you to use up to three message
parameters in the messages.
Also provided is the built-in str() method (the equivalent of the $R{} syntax inside the
report expressions), which gives access to the resource bundle content based on the
report locale.
For date and time formatting, the built-in REPORT_TIME_ZONE parameter can be used to ensure proper time transformations. In the generated output, the library keeps information about the text run direction so that documents generated in languages that have right-to-left writing (like Arabic and Hebrew) can be rendered properly. If an application relies on the built-in Swing viewer to display generated reports, then it also must be internationalized by adapting the button ToolTips or other texts displayed. This is very easy to do since the viewer relies on a predefined resource bundle to extract locale-specific information. The base name for this resource bundle is net.sf.jasperreports.view.viewer .
Internationalization Example Let's take a look into the /src folder of this sample. There are several .properties files containing
localized messages corresponding to the same keys. For example, in the i18n.properties file (which is the default resource bundles file),
we'll find a line having the key text.message , and the associated message The program picked up {0} as a random number. :
text.message=The program picked up {0} as a random number.
In the localized i18n_pt_PT.properties file, the same line will read:
text.message=O programa escolheu acima {0} como um número aleatório.
Images can be also localized. There are several .gif files in the /src folder, containing images of national flags.
When a report locale is set, the corresponding national flag image will be loaded and inserted into the generated report.
The engine reads the localized .gif name using the image.flag key present in the resource bundle files.
Now, in the reports/I18nReport.jrxml template, the root name of the default resource bundle is specified using the
resourceBundle attribute in the <jasperReport /> element:
resourceBundle="i18n"
In order to set localized texts or images in their placeholders, either the $R{} syntax or the related
msg() or str() methods should be used.
For images (the $R{} syntax):
<image scaleImage="Clip">
For texts (the $R{} syntax):
<textField isStretchWithOverflow="true" isBlankWhenNull="true">
or (the msg() method):
<textField isStretchWithOverflow="true" isBlankWhenNull="true">
When you run the sample in order to visualize it from within the built-in Swing viewer (by typing the ant clean javac compile fill view command in a command line), you will be asked for the report locale twice.
That's because your first choice is used at fill time in order to generate the localized report, and the second choice is used for
customizing the viewer itself.
For example, if you choose first the fr_FR - français (France) from the drop-down list, and then pt_PT - português (Portugal), your report will be written in French, but all controls in the viewer (buttons, text boxes, drop-down lists) will have Portuguese tooltips. In order to figure out more on internationalization, just test this sample by running from the command line the ant test view command.
It will generate all supported document types containing the sample report in the /build/reports directory, and then the report will be loaded and visualized into the built-in viewer.
|
||||
|
|
© 2001-2010 Jaspersoft Corporation www.jaspersoft.com |