Properties File Syntax

The locale bundle for a JasperReports Server Domain is a standard Java properties file. Inside the properties files, each entry is of the form:

key=value

Each .properties file is a text file containing these 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 Domain 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.

The Java language specifies the format and encoding of the file, but the meaning of each key name is based on the Domain to which it is attached.

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

Property 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.

Example of an 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.
...