Locale Bundles

A locale bundle is a set of properties files used in localizing software. The files contain other-language versions of the labels and messages that are displayed to users. When a user’s operating environment specifies a locale, the server looks for the corresponding locale bundle and uses the labels and messages it contains. The server interface is already internationalized, and Domains make reports internationalizable so that users can create and view reports in their language.

A locale bundle for a Domain consists of a single file containing all the internationalization keys for the sets and items in the Domain. Each key is associated with the text for the label or description in the language of the target locale. The name of the file includes the target locale, so the server automatically associates it with the user’s locale when needed.

When a Domain with locale bundles is used to create or run a report, the server resolves each label to display as follows:

•    The server looks for a bundle corresponding to the current locale and for the key corresponding to the label. If both exist, the server displays the text associated with the key; if the bundle or key does not exist, then

•    The server looks for the same key in a default bundle among the resources. If these exist, it displays the text associated with the key in the default bundle; if the default bundle or key does not exist, then

•    It displays the text of the label property defined in the Domain design; if no label is defined, then

•    It displays the value of the id property.

Descriptions are localized in the same manner, except they are left blank if there is no locale bundle, default bundle, or description property defined.

There are several strategies for managing the locale bundles. Based on the search algorithm above and your localization needs, you could have one of the following scenarios:

•    You do not have any localization needs at the time you create the Domain. You give all labels and descriptions a clear and complete text within the design, and you leave the key names undefined. As your enterprise grows, users in another country need to create reports based on the Domain. To create localized text for those users, edit the Domain design to define the internationalization keys, then create the locale bundle. You can create locale bundles incrementally each time you have users who need a new language. Users in your home country who do not specify a locale still see the labels and description in the original Domain design.

•    You want to create the Domain tailored to a multilingual environment where reports need to be localized for each user’s specified locale. In this case, you do not specify any labels or descriptions in the Domain design, only the internationalization keys. Then you create a default locale bundle that gives the clear and complete text of every label and description in your preferred language. In this way, all user-visible text for the Domain is in the standard format of a locale bundle, and you can use specialized software or translation services to create all the locale bundles you need. In case a label or description is not translated, users see the text of the default locale bundle.

Defining the Internationalization Keys

In the Domain Designer, the name of the internationalization keys are defined by the Name Key and Descriptions Key properties on each set and item defined on the Display tab. By default, these properties are blank. You may name the keys in any way you want, as long as each key is unique among all keys within the Domain.

To automate this process, use Export Bundle on the Display tab of the Domain Designer. The Confirm dialog box appears.

Exporting a bundle performs two tasks:

•    Automatically generates all the key names

•    Outputs a locale bundle stub

You have the option of generating only the label keys, only the description keys, both, or neither. When you click OK, the generated key names are added to all the blank Name Key and Descriptions Key properties; any keys that already exist are not be modified. In order to guarantee uniqueness, the generated key names have the following format:

SET_ID.LABEL

SET_ID.DESCR

SET_ID.ITEM_ID.LABEL

SET_ID.ITEM_ID.DESCR

The locale bundle stub is a properties file in the proper format containing all the defined keys, ready for translation. The locale bundle stub is further explained in the next section.

In the design schema, the name of the keys are given by the labelId and descriptionId attributes on each itemGroup and item element. If these attributes are missing or defined with an empty value (""), the keys are not defined. To define the keys, give these attributes a value that is unique among all the keys. If you have many sets and items, it may be easier to upload the design file in a Domain and open it in the Domain Designer. You can then generate the keys automatically, export the bundle as explained above, and export the XML design file that now contains the generated keys.

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 section 6.2, “Example of Creating a Domain,” on page 138. 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 is the same as ASCII for all English non-accented characters. For international characters that are not in ISO-8859-1, use Unicode escape sequences (for example \u00e9 is é). The following example shows the French translation for the properties file shown above, including the UTF-8 code for accented characters and other symbols.

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