Creating Locale Bundle Files

A locale bundle for a Domain is a Java properties file where each property name is a unique internationalization key from one of the labels or descriptions in the design. The value of each property is the text for the label or description in the target language. The name of the file identifies the locale in the form <any_name>_<locale>.properties, where <locale> is any Java-compliant locale identifier, for example fr or fr_CA. If the _<locale> part of the file name is omitted, the file designates the strings for the default locale.

Usually, the set of keys is identical in the properties file of each locale bundle, but this is not necessary. The text for a given key in a given locale is determined by the algorithm given in Locale Bundles.

Often, it is simplest to create the properties files from the stub exported by the Domain Designer. Whether you have created the design in the Domain Designer or in an external file uploaded to the Domain Designer, use Export Bundle in the menu bar to export a blank properties file. Optionally, you may generate any missing keys, as described in the previous section.

The following example shows part of the properties file output for the Domain created in Example of Creating a Domain. All of the internationalization keys were generated automatically as well. As the example shows, sets and items in the bundle stub appear in the same order as on the Display tab of the Domain Designer:


The syntax for the properties file is the same as for Java properties files. Generally, everything after the = symbol is part of the translated text. Java properties files use the ISO-8859-1 (Latin-1) encoding that supports most, but not all, accented characters. For accented characters that are not in ISO-8859-1, or any other international characters, use Unicode escape sequences. For example, the œ character has the Unicode escape sequence \u0153.

The following example shows the French translation for the properties file 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.

ACCOUNTS.DESCR=Détails des comptes clients.
ACCOUNTS.ACCOUNT_TYPE.DESCR=Type du compte client.
ACCOUNTS.INDUSTRY.DESCR=Industrie d\u2019activité primaire.
ACCOUNTS.CITY_AND_STATE.DESCR=Ville et région ou état du client.
USERS1.DESCR=Responsable du compte client.
USERS1.LAST_NAME.DESCR=Nom de famille.

After creating the properties file for the first locale, you can simply copy the file and change the _<locale> designator to begin translation of another locale bundle. A best practice is to save a blank properties file or the default locale bundle as a template for future translations. Also, if you change the Domain design, you can export the locale bundle again and compare it to the template to find all new keys.

You can create and edit the properties file in any text editor. Certain editors provide features for editing properties files. There are also translation products that manage all of the resource bundles together, allowing you to translate in parallel and find missing keys and missing translations.

Regardless of how you edit properties files, when all translations are finished, you need to upload them as locale bundles to the Domain. See the procedure in Security and Locale Information for a Domain for instructions about uploading locale bundles. Also, if you change a Domain design and need to modify the properties files, follow that same procedure to download, modify, and upload each locale bundle.

For additional information about locales and locale bundles in JasperReports Server, see the Localization chapter in the JasperReports Server Administrator Guide.