JasperReports Server and iReport Designer Internationalization

Introduction

Internationalization is quickly becoming a growing requirement for many companies as they expand their offices to various locations around the world. Many companies are searching for a robust BI platform with multi-language support. This tutorial will identify various areas within the Jaspersoft Business Intelligence suite that utilize internationalization.

Note: To follow along with the example scenario, download the sample files located here.

Objectives

This guide will enable you to:

Pre-Requisites

Install the JasperServer samples on your JasperServer installation.

Understanding the 'Bundles' Concept

The concept of internationalization is the same across JasperServer UI, reports, and Domains. In order to understand the concept of internationalization, first review the concept of bundles, which is a key building block.

  • A locale bundle is a text file that contains a key and its value.
    • Example: ADH_003a_TABLE=Table indicates that the object ADH_003a_TABLE will be displayed as “Table” to the user.
  • The name of this file must follow the following format:

Name_Suffix.properties

  • Name: Name of your ‘bundle’
    • Choose a name that describes what the bundle is related to
    • Example: adhoc_messages
  • Suffix: Country code your language uses
  • How the system will find which translation to choose according to the language the user selects
  • .properties: Mandatory extension for bundles

Notes:

  • A missing key may cause a failure in the system. You must have ALL keys specified in the bundle file even if not all keys have a value
  • A bundle file without a suffix means is used as default in the event that the system does not find a bundle for the specified language

Modifying JasperServer Bundles

Locale bundles that use Unicode, accents or special characters have to be coded like \u00e0 for à.

Step Action
1 Go to the …\jasperserver-pro\WEB-INF\bundle directory

2

All properties files are organized by application name for easy access.

Example: Edit adhoc_messages_fr.properties file as follows, (located in the folder you downloaded above) and then save it.

3

Check the result:

  1. Log into JasperServer as jasperadmin / jasperadmin.

    Note: Make sure to click the locale and time zone link and specify the appropriate locale. In this example, we specify French.

  2. Go to Create > Ad Hoc Report

    You should see the following: on the left side the original translation, and on the right the modified one

    Tip: Internationalization can be used for formatting of dates and numeric values.

    Edit the adhoc_masks_XX.propeties file to define additional translations.

Implementing a New Language

To implement a new language, copy all default bundles and rename them using the country code of your new language.

Example: In this example we will be defining translations for Danish. The country code is da (alpha-2 code).

Step Action
1 Go to the …\jasperserver-pro\WEB-INF\bundle directory, and open the file: adhoc_messages.properties

2

Rename (use Save As) the file to: adhoc_messages_da.properties

Edit the file as follows in the image below:

3

Create a new entry for your language:

  1. Stop JasperServer

  2. Go to the …\jasperserver-pro\WEB-INF directory

  3. Edit the file ApplicationContext-Security.xml

  4. Localize the bean (approx line 176):

    <property name="locales">
    <list>
  5. Add your language in the list:

    <value type="java.util.Locale">da</value>

  6. Start JasperServer

  7. Go to the login page select the new language

  8. Click Show locales and timezone to display the list

  9. Log into JasperServer as jasperadmin / jasperadmin

  10. Go to Create > Ad Hoc Report

  11. View the result:

Internationalizing Domains

Prior to internationalizing Domains, you first want to finalize and publish the Domain to JasperServer. In general, translations are typically defined once the Domain is complete and validated.

Example: We create the default translation and the French translation for a Domain.

Step Action

1

  1. Log into JasperServer as jasperadmin / jasperadmin

  2. Go to View > Repository

2

  1. Select the Domain folder

  2. Click the Add Resource > Domain icon

  3. In Data Source section, click Browse, then select Organization > Analysis Components Analysis Data Sources > Foodmart Data Source

  4. Click OK

  5. In the Properties section, Display Name field, enter: employee_domain

  6. In the Design section, click the Upload tab, then select the provided file (domain_schema.xml)

3

Launch the Domain Designer

  1. Select the Edit tab.

  2. Click Launch Domain Designer …

  3. In the top-right corner click the Export Bundle Stub icon

    The following window appears: check the Autogenerate Key label box to get the labels keys

    Optionally, check the Autogenerate Key description box if you wish to generate a description

    This will generate all the keys needed to create the bundle.

    Download the file and save it to your drive

    Best Practice: Change the name to the Domain’s name

    Example: Rename it to: employee_domain.properties

4

The initial export will serve as the default translation. Additionally, we will define a French translation.

Example: Translate the bundle into French and save it as employee_domain_fr.properties

5

Publish the translation to JasperServer:

  1. Log into JasperServer as jasperadmin / jasperadmin

  2. Go to View > Repository

  3. Select the Domain folder and then the Domain “employee_domain

  4. Right click and choose Edit

6 Select Resources breadcrumb at the top of the screen, and then click Add Local Bundle

7

  1. On the Local File tab, find the employee_domain.properties and upload it.

  2. Click OK

8 Redo Step 7 for the file employee_domain_fr.properties

9

Check your results:

  1. Log into JasperServer as jasperadmin / jasperadmin

  2. Go to Create > Ad Hoc Report

  3. Create a new Ad Hoc report using your new Domain

Note: Make sure to specify the appropriate locale.

Internationalizing Reports

Internationalizing Reports follows the same concept as internationalizing Domains. All labels that need to be translated are declared: $R {key_name}

Once the layout of the report has been finalized, create a bundle containing all the keys and their values (translations).

Example: We translate a report to French.

Step Action
1 Open iReport

2

Create a new empty report.

  1. Add a text field $R{hello}

  2. In the Report Inspector, right click on report name then select Properties.

  3. In resource bundle set Resource Bundle to localereport

    • This represents the base name of the local bundle to use; you do not have to add the extension.

  4. Create the localereport.properties file: Hello=Hello word

    Translate the text as required, and save it as localereport_fr.properties: Hello=Bonjour a tous

3 Publish the report using the JasperServer plugin.

4

Once the report is published, open the report unit, right click on the Resources folder, then choose Add > Resource Bundle

5

Complete the Import Resource screen the form as follows; ensure you provide the full name.

6

Repeat this for all languages using the example: localereport_fr.properties

What's Next?

Resource for searching all language codes is here.

Tip: Select by alpha- codes.

Written By

This tutorial was written by Guillaume Autier, Sales Engineer, June 2009

Feedback
randomness