<html xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://jasperreports.sourceforge.net/jasperreports">
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>JasperReports 4.0.2 - I18n Sample</title>
<style type="text/css">
.title {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 28px;
font-weight: normal;
}
.toc {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.name {
font-family: Courier New, Courier, serif;
font-size: 16px;
font-weight: bold;
}
.label {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: bold;
font-style: italic;
}
.description {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: normal;
}
.value {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.element {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.attribute {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: bold;
}
.code {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.copy {
font-decoration: none;
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 8pt;
font-style: normal;
color: #000000;
}
.subtitle {
font-family: inherit;
font-size: inherit;
font-style: inherit;
font-weight: bold;
text-decoration: none;
color: inherit;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="top"></a>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td colspan="2" align="right"><span class="element"><a href="../../sample.reference.html">Sample Reference</a> - <a href="../../schema.reference.html">Schema Reference</a> - <a href="../../config.reference.html">Configuration Reference</a> - <a href="http://jasperreports.sourceforge.net/api/index.html">API (Javadoc)</a></span>
<br>
</td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
<tr valign="middle">
<td nowrap="true"><span class="title">JasperReports - I18n Sample (version 4.0.2)</span></td><td align="right"><img src="../../resources/jasperreports.png" border="0"></td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
</table>
<br>
<span class="description"><span class="description">Shows how a report could be rendered in different languages.</span></span>
<br>
<br>
<span class="element"><a href="http://sourceforge.net/projects/jasperreports/files/jasperreports/JasperReports%204.0.2/jasperreports-4.0.2-project.zip/download" target="_blank">Download All Sample Source Files</a></span>
<br>
<span class="element"><a href="http://jasperforge.org/scm/viewvc.php/tags/jr-4-0-2/jasperreports/demo/samples/i18n/?root=jasperreports" target="_blank">Browse Sample Source Files on SVN</a></span>
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td style="width: 20px;">
<br>
</td><td>
<br>
</td>
</tr>
<tr>
<td colspan="2"><span class="label">Main Features in This Sample</span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#i18n">Internationalized Report Templates</a></span></td>
</tr>
</table>
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td width="80%">
<br>
</td><td width="20%">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="i18n"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Internationalized Report Templates</span></td><td align="right"><span class="copy">Documented by
<a href="mailto:shertage@users.sourceforge.net" class="copy">Sanda Zaharia</a></span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
How to generate reports in different languages using internationalization support.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">0.6.2</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
<b>Internationalization Overview</b>
<br>
<br>
This sample illustrates the best way to configure a report that need to be run in different places in the world.
<br>
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.
<br>
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.
<br>
<br>
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 <span class="code"><code>java.util.ResourceBundle</code></span> instances.
JasperReports lets you associate a <span class="code"><code>java.util.ResourceBundle</code></span> with the report
template, either at design time (by using the <span class="code"><code>resourceBundle</code></span> attribute) or at
runtime (by providing a value for the built-in <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/JRParameter.html#REPORT_RESOURCE_BUNDLE" target="_blank">REPORT_RESOURCE_BUNDLE</a></span> parameter).
If the report needs to be generated in a locale that is different from the current one,
the built-in <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/JRParameter.html#REPORT_LOCALE" target="_blank">REPORT_LOCALE</a></span> parameter can be used to specify the runtime locale when filling the
report.
<br>
To facilitate the report internationalization, a special syntax is available inside report
expressions to reference <span class="code"><code>java.lang.String</code></span> resources placed inside a
<span class="code"><code>java.util.ResourceBundle</code></span> object associated with the report. The <span class="code"><code>$R{}</code></span> syntax is for
wrapping resource bundle keys to retrieve the value for that key.
<br>
For formatting messages in different languages based on the report locale, a built-in
method inside the report’s <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/fill/JRCalculator.html" target="_blank">JRCalculator</a></span>
offers functionality similar to the <span class="code"><code>java.text.MessageFormat</code></span> class. This method,
<span class="code"><code>msg()</code></span>, has three convenient signatures that allow you to use up to three message
parameters in the messages.
<br>
Also provided is the built-in <span class="code"><code>str()</code></span> method (the equivalent of the <span class="code"><code>$R{}</code></span> syntax inside the
report expressions), which gives access to the resource bundle content based on the
report locale.
<br>
For date and time formatting, the built-in <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/JRParameter.html#REPORT_TIME_ZONE" target="_blank">REPORT_TIME_ZONE</a></span> parameter can be used to
ensure proper time transformations.
<br>
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.
<br>
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
<span class="code"><code>net.sf.jasperreports.view.viewer</code></span>.
<br>
<br>
<b>Internationalization Example</b>
<br>
<br>
Let's take a look into the <span class="code"><code>/src</code></span> folder of this sample. There are several <span class="code"><code>.properties</code></span> files containing
localized messages corresponding to the same keys. For example, in the <span class="code"><code>i18n.properties</code></span> file (which is the default resource bundles file),
we'll find a line having the key <span class="code"><code>text.message</code></span>, and the associated message <span class="code"><code>The program picked up {0} as a random number.</code></span>:
<br>
<br>
<span class="code"><code>text.message=The program picked up {0} as a random number.</code></span>
<br>
<br>
In the localized <span class="code"><code>i18n_pt_PT.properties</code></span> file, the same line will read:
<br>
<br>
<span class="code"><code>text.message=O programa escolheu acima {0} como um número aleatório.</code></span>
<br>
<br>
Images can be also localized. There are several <span class="code"><code>.gif</code></span> files in the <span class="code"><code>/src</code></span> 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 <span class="code"><code>.gif</code></span> name using the <span class="code"><code>image.flag</code></span> key present in the resource bundle files.
<br>
Now, in the <span class="code"><code>reports/I18nReport.jrxml</code></span> template, the root name of the default resource bundle is specified using the
<span class="code"><code>resourceBundle</code></span> attribute in the <span class="code"><code><jasperReport /></code></span> element:
<br>
<span class="code"><code>resourceBundle="i18n"</code></span>
<br>
In order to set localized texts or images in their placeholders, either the <span class="code"><code>$R{}</code></span> syntax or the related
<span class="code"><code>msg()</code></span> or <span class="code"><code>str()</code></span> methods should be used.
<br>
<br>
For images (the <span class="code"><code>$R{}</code></span> syntax):
<br>
<br>
<span class="code"><code>
<image scaleImage="Clip">
<br>
<reportElement positionType="Float" x="20" y="20" width="100" height="50"/>
<br>
<imageExpression class="java.lang.String"><![CDATA[$R{image.flag}]]></imageExpression>
<br>
</image>
</code></span>
<br>
<br>
For texts (the <span class="code"><code>$R{}</code></span> syntax):
<br>
<br>
<span class="code"><code>
<textField isStretchWithOverflow="true" isBlankWhenNull="true">
<br>
<reportElement positionType="Float" x="20" y="100" width="530" height="20"/>
<br>
<textElement textAlignment="Justified">
<br>
<font size="14"/>
<br>
</textElement>
<br>
<textFieldExpression class="java.lang.String"><![CDATA[$R{text.paragraph1}]]></textFieldExpression>
<br>
</textField>
</code></span>
<br>
<br>
or (the <span class="code"><code>msg()</code></span> method):
<br>
<br>
<span class="code"><code>
<textField isStretchWithOverflow="true" isBlankWhenNull="true">
<br>
<reportElement positionType="Float" x="20" y="210" width="530" height="20" forecolor="#FF0000"/>
<br>
<textElement>
<br>
<font size="14"/>
<br>
</textElement>
<br>
<textFieldExpression class="java.lang.String"><![CDATA[msg($R{text.message}, $P{number})]]></textFieldExpression>
<br>
</textField>
</code></span>
<br>
<br>
When you run the sample in order to visualize it from within the built-in Swing viewer
(by typing the <span class="code"><code>ant clean javac compile fill view</code></span> 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.
<br>
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.
<br>
<br>
<b>Running the Sample</b>
<br>
<br>
Running the sample requires the <a href="http://ant.apache.org/" target="_blank" class="element">Apache Ant</a> library. Make sure that <span class="code"><code>ant</code></span> is already installed on your system (version 1.5 or later).
<br>
In a command prompt/terminal window set the current folder to <span class="code"><code>demo/samples/i18n</code></span> within the JasperReports source project and run the <span class="code"><code>> ant test view</code></span> command.
<br>
It will generate all supported document types containing the sample report in the <span class="code"><code>demo/samples/i18n/build/reports</code></span> directory.
<br>
Then the report will open in the JasperReports internal viewer.
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
</table>
<br>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td>
<hr size="1">
</td>
</tr>
<tr>
<td align="center"><span class="copy">© 2001-2010 Jaspersoft Corporation <a href="http://www.jaspersoft.com" target="_blank" class="copy">www.jaspersoft.com</a></span></td>
</tr>
</table>
</body>
</html>
