Localizing Domains

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.

JOINTREE_1.ACCOUNTS.LABEL=
JOINTREE_1.ACCOUNTS.DESCR=
JOINTREE_1.ACCOUNTS.NAME.LABEL=
JOINTREE_1.ACCOUNTS.NAME.DESCR=
JOINTREE_1.ACCOUNTS.ACCOUNT_TYPE.LABEL=
JOINTREE_1.ACCOUNTS.ACCOUNT_TYPE.DESCR=
JOINTREE_1.ACCOUNTS.INDUSTRY.LABEL=
JOINTREE_1.ACCOUNTS.INDUSTRY.DESCR=
...

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.

JOINTREE_1.ACCOUNTS.LABEL=Comptes
JOINTREE_1.ACCOUNTS.DESCR=Détails des comptes clients.
JOINTREE_1.ACCOUNTS.NAME.LABEL=Client
JOINTREE_1.ACCOUNTS.NAME.DESCR=Nom du client
JOINTREE_1.ACCOUNTS.ACCOUNT_TYPE.LABEL=Type
JOINTREE_1.ACCOUNTS.ACCOUNT_TYPE.DESCR=Type du compte client.
JOINTREE_1.ACCOUNTS.INDUSTRY.LABEL=Industrie
JOINTREE_1.ACCOUNTS.INDUSTRY.DESCR=Industrie d\u2019activité primaire.
...
Version: 
Feedback
randomness