You can configure Domains to provide localized text for the labels and descriptions of presentation elements (data islands, sets, and items). Text you localize appears in Ad Hoc views and reports built from your Domains, based on the locale specified in the user’s operating environment.
Properties File Format
To localize Domain labels and descriptions, you must create a properties file for each locale you want to support. You can also create an optional "default" file that is used as a fallback whenever a message is missing in the properties file for the current locale.
Domain localization in JasperReports Server is implemented using Java locales and resource bundles. A single properties file is sometimes called a "locale bundle." |
Each .properties file is a text file containing key-value pairs for a locale:
• | The keys, when present, are the same across all the .properties files for the supported locales. A file can omit some of the keys. |
• | By default, the keys are based on IDs in the presentation, but you can create your own keys if you prefer. |
• | The values are the labels and descriptions in the language of the target locale. |
• | File names are of the form <any_name>_<locale>.properties, where: |
• | <any_name> is arbitrary and the same for all files. |
• | <locale> is any Java-compliant locale identifier, for example fr or fr_CA. |
• | You can optionally include a default .properties file, which is used for the default locale or when a key is missing or empty in one of the other .properties files. The default properties file name is <any_name>.properties. It does not have a language extension. |
Keys and Values
Inside the properties files, each entry is of the form:
key=value
Key Names
You can use the default key names generated by JasperReports Server or you can assign your own names to the label and description keys. Key names must satisfy the following rules:
• | Each key name must be unique among all key names in the Domain. |
• | Key names can only use characters from the ISO Latin-1 set, digits, and underscores (_). |
In the Domain Designer, you can define key names using the Label Key and Descriptions Key properties on the Data Presentation tab. In the XML design file, these correspond to the labelId and descriptionId attributes on the itemGroup or item element.
If no name has been assigned to the label key or description key, JasperReports Server expects key names in a hierarchical format, for example:
<dataIslandID>.LABEL
<dataIslandID>.DESCR
<dataIslandID>.<setID1>...<setIDn>.LABEL
<dataIslandID>.<setID1>...<setIDn>.DESCR
<dataIslandID>.<setID1>...<setIDn>.<item>.LABEL
<dataIslandID>.<setID1>...<setIDn>.<item>.DESCR
Values
Values are strings that specify the text to use for the locale associated with the file. Values must satisfy the following rules:
• | Everything after the = symbol is part of the translated text. |
• | The properties files use the ISO-8859-1 (Latin-1) encoding that supports most, but not all, accented characters. |
• | For characters that are not in ISO-8859-1, use Unicode escape sequences. For example, the œ character has the Unicode escape sequence u0153. |
You can define values in several places. JasperReports Server looks for values in the following order, and displays the first non-empty value it finds:
1. | In the properties file for the current user's locale. |
2. | In the default properties file. |
3. | In the Label or Descriptions property on the Data Presentation tab in the Domain Designer. In the XML design file, these correspond to the label and description attributes on the itemGroup or item element. |
4. | If no value is found in any of the previous locations, then: |
• | For a label, JasperReports Server uses the ID from the Data Presentation tab, which is the same as the value of the id property in the XML file. |
• | For a description, the result is left blank. |
Examples
Example of File Naming for Locales
The following table shows an example relationship between file names, key names, and values in two files, a default file in English and a file of French translations.
Language | Locale | File Name | Sample Contents |
English | default | Labels.properties | JOINTREE_1.SET1.STORE_CITY.LABEL=City JOINTREE_1.SET1.STORE_CITY.DESCR=Store city |
French | fr | Labels_fr.properties | JOINTREE_1.SET1.STORE_CITY.LABEL=Ville JOINTREE_1.SET1.STORE_CITY.DESCR=Ville du magasin |
Example of Empty Properties File
The following example shows part of a typical properties file created from the Domain Designer, with internationalization keys generated automatically. Sets and items in the file appear in the same order as on the Data Presentation tab of the Domain Designer. If you have already entered values for the Label Key or Descriptions Key for an item, the value is filled in.
Example of a Localized File
The following example shows the French translation for the properties file fragment above, including accented characters.
The single straight quote (') sometimes causes issues when processed in Domain properties files. To avoid this issue, use the right single quote (’) by its Unicode sequence u2019, as shown in the following example. |
Recommended Comments
There are no comments to display.