JasperReports 4.6.0 - I18n Sample

JasperReports Ultimate Guide - Sample Reference - Schema Reference - Configuration Reference - API (Javadoc)

JasperReports - I18n Sample (version 4.6.0)

Shows how a report could be rendered in different languages.

Download All Sample Source Files
Browse Sample Source Files on SVN


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 This sample illustrates the best way to configure a report that need to be run in different places in the world. French customers would prefer to see their data reported in French, Chinese customers would like to see the same data translated into Chinese, and Greek customers would think that reporting the same data in Greek would be the best approach. In such cases, writing the same report for each different language implies a lot of redundant work, which is not recommended. Only pieces of text differing from language to language should be written separately, and loaded into text elements at runtime, depending on locale settings. This is the purpose of the report internationalization. Internationalized reports once written, can run everywhere. Paragraphs that need to be translated from a language to another are stored in localized resource bundle files, loaded into `java.util.ResourceBundle` instances. 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 the 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"> <reportElement positionType="Float" x="20" y="20" width="100" height="50"/> <imageExpression class="java.lang.String"><![CDATA[$R{image.flag}]]></imageExpression> </image>` For texts (the `$R{}` syntax): `<textField isStretchWithOverflow="true" isBlankWhenNull="true"> <reportElement positionType="Float" x="20" y="100" width="530" height="20"/> <textElement textAlignment="Justified"> <font size="14"/> </textElement> <textFieldExpression class="java.lang.String"><![CDATA[$R{text.paragraph1}]]></textFieldExpression> </textField>` or (the `msg()` method): `<textField isStretchWithOverflow="true" isBlankWhenNull="true"> <reportElement positionType="Float" x="20" y="210" width="530" height="20" forecolor="#FF0000"/> <textElement> <font size="14"/> </textElement> <textFieldExpression class="java.lang.String"><![CDATA[msg($R{text.message}, $P{number})]]></textFieldExpression> </textField>` 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. Running the Sample Running the sample requires the Apache Ant library. Make sure that `ant` is already installed on your system (version 1.5 or later). In a command prompt/terminal window set the current folder to `demo/samples/i18n` within the JasperReports source project and run the `> ant test view` command. It will generate all supported document types containing the sample report in the `demo/samples/i18n/build/reports` directory. Then the report will open in the JasperReports internal viewer.