Creating a Locale

When you want to create other locales for JasperReports Server, translation is only one aspect of localization. Creating a locale includes these tasks:

Translating labels and messages
Creating a Resource Bundle
Setting Date and Datetime Formats
Setting Data Format Masks

The tasks in this section require you to edit these files:



Purpose of Edits

*.properties files


Translating labels and messages


Changing date formats



Changing format masks

About Properties Files

Resource bundles for JasperReports Server and Jaspersoft OLAP are Java properties files found in the .../WEB-INF/bundles directory. The properties files contain all the labels and messages used in JasperReports Server and Jaspersoft OLAP.

A bundle includes a default locale (for example,, which is written in U.S. English. Then it consists of all the properties files with the same base name, but different locale (such as Each file translates all of the strings of the default file into the language given by the locale. The Java programming language has rules for specifying locales and alternate locales and determining which locale in the bundle to use.

Default Resource Bundles in JasperReports Server

File in .../WEB-INF/bundles


Text spoken in accessibility software such as screen readers.

Labels and messages for the Ad Hoc Filters panel.

Masks (data formats) for values appearing in the Ad Hoc Editor.

Labels and messages for the Ad Hoc Editor.

Messages for attribute validation.

Messages for attribute dialogs.

Labels and messages used by the pop-up calendar dialog.



Bundle for tests.


Labels and messages for the Create Domain dialog.


Labels and messages for the Domain Designer UI.

Labels for the new home page introduced in version 5.5.


Labels and messages for the AWS (Amazon Web Services) machine images.


Messages for charts in the report viewer.


Labels and messages for the report viewer.

Configuration properties for dates and date-times.

Labels and messages used in the main JasperReports Server user interface.

Messages used in errors and exceptions, both in the UI and in the log messages.

Labels and messages used when validating licenses.

Internal log messages.

Labels and messages for the menu bar and old Home page.

Labels and messages for the Choose Data dialog (for creating a Domain Topic before using Ad Hoc Editor).


Labels and messages for the report options dialog.


Labels for lists of values in input controls.

Validation messages for the report scheduler. Messages used by input validation.

Labels and messages for the Domain designer and Ad Hoc data policies. Messages for dashboard dialogs.

Default Resource Bundles in Jaspersoft OLAP

File in .../WEB-INF/bundles


Labels and messages in the OLAP settings UI.

Labels and messages in the commercial edition OLAP viewer.

Labels and messages in the community edition OLAP viewer.


MDX validation error messages specific to the internal analysis engine.

The standalone import and export tools have their own bundles located outside of the web app. The following bundles are located in the WAR file distribution package, under the buildomatic folder.

Default Resource Bundles for and

File in buildomatic/conf_source/ieCe/bundles


File in buildomatic/conf_source/iePro/bundles


Labels and messages for js-export --help.

Labels and messages for export in commercial editions.

Labels and messages export in commercial editions.

Messages used in errors and exceptions, both in the UI and in the log messages.

If you use the JasperReports Server portlet to display JasperReports Server content in a portal (such as Liferay), the deployed portlet includes properties files, as well:





.../WEB-INF/bundles under the location where the portlet is deployed. For example:

C:\liferay\webapps\<portlet_context_name>\WEB-INF\bundles (where <portlet_context_name> is the name specified when the JasperReports Server portlet was deployed).

Labels and messages that appear in the portlet, including the help text.

Note that this does not include text in specific reports; to localize the report's content, you must upload its resource bundle to the repository.

Creating a Resource Bundle

Create a resource bundle by making a copy of each *.properties file, using the following syntax for the copy's file name:



<default_file_name> is the name of the default version of the properties file, and

<locale> is a Java-compliant locale identifier.

For example, consider the core JasperReports Server resource bundle. For various locales, it might be named as follows:


File Name

Default (English)


French in Switzerland

For a list of Java-compliant locales, please refer to the Java documentation.

The resource bundles described in this document consist of locale-specific Java properties files. 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 é).

To create a new JasperReports Server resource bundle:

1. Copy each of the properties files (keeping them in the same directory as the originals) and rename them according to your locale.
2. Translate each *.properties file's labels and messages into the new language.

Some of the strings in the properties files are date formats and format masks that may need to be edited for the new locale. For more information, refer to Setting Date and Datetime Formats.

3. Save the files.
4. If the new locale requires specific character encoding or fonts, ensure that JasperReports Server and the third party software it relies on are configured to support them. For more information, refer to Configuring JasperReports Server for Multibyte Fonts.

The new locale is not available in JasperReports Server until you follow the steps described in Specifying Additional Locales.

Setting Date and Datetime Formats

Each locale may have its own rules for displaying dates and datetime values. System date and datetime formatting is controlled by four patterns that are specified in the jasperserver_config_<locale>.properties file associated with a particular locale.

For example in the English resource bundle, the four entries are:

datetime.format=dd-MM-yyyy HH:mm
calendar.datetime.format=%d-%m-%Y %H:%M

The first two keys are used to parse and format dates and datetime values using an internal java.util.DateFormat object across the whole application. These patterns should be non-localized date patterns, in accordance with the Java Development Kit (JDK) syntax.

The other two keys are used by the calendar control, which formats the user-selected date and datetime values in accordance with its own pattern syntax.

To change the system date and datetime formatting for a new locale, edit the strings specified by these keys.

Setting Data Format Masks

Each locale may have its own format masks that determine how numbers appear in the Ad Hoc Editor. To make the data format masks vary by locale, you must create an adhoc_masks file for the new locale. To do so, copy the file to a new name that specifies the new locale and change the masks defined in the new file. For example, the French file would be named

The data format masks described in this section are used in the Domains and in the Ad Hoc Editor; they appear in Ad Hoc views as well as JRXML reports based on Domains. They're not applicable to Jaspersoft OLAP.

Customize the available data format masks for dates, integers, and decimals by editing the existing masking entries or adding new ones. The default entries are given in the following table:

Data Format Mask Properties

Appearance in en_US Locale

ADH_100_MASK_date_0 = short,hide
ADH_100_MASK_date_1 = long,hide
ADH_100_MASK_date_2 = short,medium
ADH_100_MASK_date_3 = medium,medium
ADH_100_MASK_int_0 = #,##0
ADH_100_MASK_int_1 = 0
ADH_100_MASK_int_2 = $#,##0;($#,##0)
ADH_100_MASK_int_3 = #,##0;(#,##0)
ADH_100_MASK_dec_0 = #,##0.00
ADH_100_MASK_dec_1 = 0
ADH_100_MASK_dec_2 = $#,##0.00;($#,##0.00)
ADH_100_MASK_dec_3 = $#,##0;($#,##0)

Mar 31, 2009
March 31, 2009
Mar 31, 2009 23:59:59



The data format masks for each type are numbered consecutively from zero; create new masks by adding new entries. The keys of the new entries must follow the convention established in the default entries. For example, a new decimal data format mask might have this ID:


Date format masks are implemented using java.text.SimpleDateFormat and JasperReports extensions that provide access to predefined localized data format masks. New datetime masks must be specified in one of the following formats:

A style for the date part of the value and a style for the time part (separated by comma) or a single style for both parts. A style is one of Short, Medium, Long, Full, Default (which correspond to java.text.DateFormat styles) and Hide.
A pattern that can be supplied to java.text.SimpleDateFormat. In this case, internationalization support is limited.

Both integer and decimal data format masks are implemented with java.text.DecimalFormat, which localizes characters in the format specification. For example, consider the case of the digit grouping symbol (thousands separator): in French, it is a space; in U.S. English, it is a comma. DecimalFormat handles both cases: if the number pattern #,##0 is used, the number 6000 appears as 6 000 in the French locale and as 6,000 in the U.S. English locale.

For more information about Java's handling of decimal and date format masks, see:

By default, monetary values in Ad Hoc views are masked as USD (United States Dollars). Depending on your data, you may need to support a different currency, support more than one currency, or support currency conversion. These are three very different cases:

Supporting a different currency than USD involves changing the monetary masks to use the correct symbol for your currency (for example, replace the $ symbol in the ADH_100_MASK_dec_2 and ADH_100_MASK_dec_3 masks). However, changing this symbol does not actually convert currencies in your reports.
Supporting other currencies in addition to USD involves adding new masks. However, adding data formats does not actually convert currencies in your reports.
Supporting currency conversion is more complicated; you must consider such issues as fluctuations in conversion rates. Oftentimes, a third-party service can be used to perform currency conversion