Implementation Guide for Oracle Self-Service E-Billing > Using the Reporting Engine > Core Reporting Features >

Internationalization and Localization of Reporting

Resource bundles are used to support internationalization. This topic discusses internationalization for Velocity templates.

Because the Reporting Engine uses Velocity templates, you cannot take advantage of the JSP <message> tag or the Struts internationalization framework. Instead, the Reporting Engine has its own internationalization mechanism specially designed for Velocity templates, which has following features:

• Allows a user to specify any resource bundle, just like Struts config does.
• Allows a user to format a string as Y does, for example, My name is {0}.
• Provides a seamless integration with Struts if it is used. For example, sharing the same resource bundle.
• Offers a better way to handle default messages than Struts. In Struts, a resource that is not found is either returned as null or as ???<locale><resource_key>???. With the Reporting Engine, you can configure it to return the key itself when the value of the key is not found.

For internationalization of reporting, you translate the following text:

• Regular text on the report user interface.
• Some text coming from the data source.
• Chart, title and amount format, and so on.
• Date format, number format, and so on.

Resource Bundle Definition

The resource bundle files used by the Reporting Engine templates are defined in the report XML files under the <reports> tag. The following example comes with Oracle Self-Service E-Billling, and is defined in the telco_global.xml file.

<localizer enableMessageResources="true" defaultCode="1">
<resourceBundle name="com/edocs/app/reporting/resources/ApplicationResources" />
</localizer>

Follow these naming guidelines for localizing resource bundles:

• You must use "/ instead of "." in the name of the resource bundle, which differs from Struts message resource.
• The <localizer> tag defines how text will be localized. You can define multiple <resourceBundle> tags. Each resourceBundle tag defines a resource bundle file, and its name is defined by name attribute.

When the Reporting Engine searches for the resource bundle, it first checks whether this bundle exists as a file under EDX_HOME (the directory where you installed Oracle Self-Service E-Billling), or the current directory if EDX_HOME is not defined. If that fails, it will try to find it as a class.

The attribute enableMessageResources enables you to use Struts MessageResource to search for a resource.

The attribute defaultCode enables you to define the default behavior if a resource is not found. 0 means to use the key as the default value; 1 means to use Struts notion of "???<locale>.<key>???" and -1 means throw an exception. The default value for the attribute defaultCode is 0.

The search order for finding a resource is:

1. If the attribute enableMessageResources is true, and the Struts MessageResource does exist (it might not exist for a non-Struts application), search the resource from Struts MessageResource, and return the resource if it is found.
2. For each resource bundle defined in resourceBundle, load the bundle as either file or class, and then search the resource in the order it appears, return if found.
3. If nothing is found, use defaultCode described previously.

Follow these guidelines when defining a resource bundle:

• If you check the resource bundle name in the struts configuration file, you will notice that the same file, com/edocs/app/reporting/resources/ApplicationResources, is defined in both the Struts and report XML files. The only difference in the definitions is the file separators; reporting uses a back slash (/) and Struts uses a period (.). The same file is in two locations in order to support batch reporting. A batch job is not a Web application, so it does not have access to Struts MessageResource. This is also true if you are using the Reporting Engine at the EAR level. For example, you can generate an email message from an MDB event handler or from an EJB. However, if you are using Struts, and you using the Reporting Engine for online applications only (not batch reporting), then do not define a resourceBundle, because the online Web application can always find resources from MessageResource.
• Because the same resource is defined twice, both Struts and the Reporting Engine load the same resource bundle and cache them (twice). Usually, this is not a problem, because a resource bundle file is small. However, if you do want to reduce memory usage, you can put all the template related resources into one file. Or, you can be more selective by putting only the batch report, email, and AR-related resources into one file, and load it by using the resourceBundle tag in report xml.
• It is recommended that you define the resource bundle as flat file under EDX_HOME, which lets you modify the file and reload it using this URL without restarting:

  http://localhost:7001/ebilling/reporting/reloadReportConfig.jsp

• If you want to use a struts message source, which is loaded from the classpath, you can disable it during the development stage by setting enableMessageResource to false and loading a resource bundle from file system.
• Set the defaultCode to 1 to find all the text not being internationalized properly. You might want to set it to 0 for demonstration purposes.

Localization of Report Text

The localization of text in report is done through the #localize macro, which is defined in reporting_library.vm. It is defined as:

#macro (localize $name)

For example, in your template, you can call this macro as follows. This expression searches the report bundle to find a key with a value that matches name:

#localize("name")

All the texts defined in the report.xml file are treated as resource bundle keys. For example, report names and column labels. In the report template files, all the texts are localized through the #localize macro.

Localization of Report Data from a Data Source

By default, the text data retrieved from data source is not localized. You must turn on this option. In this case, the text data from data source will be used as keys to search reporting resource bundles.

The localization of data from data source is done through the localize attribute of transformer column configuration in report XML.

<column id="call type" localize="true" />

The column data retrieved from the database will be localized.

Localization of Charts

The chart components (chart title, labels and data) are localized by the ITransformer.writeChart() method. The chart tile is searched as a regular resource bundle name. Label and data are localized if the localize attribute is set to true for the corresponding columns.

Locale

To support internationalization, you must pass the Locale object to ReportContext by calling setLocale(). If ReportContext does not have a locale defined, when you call the IReportActionHelper.execute() method, it puts the Struts locale object in session.

Dynamic Localization

Velocity is used to support localization. Velocity acts similar to the way java.text.MessageFormat does, and achieves the same result. The Reporting Engine parses the resource value as a Velocity template, whose resource key ends with .vm, and returns the parsed value. For example,

rpt.test.vm=My name is $name.

Object name must come from the report context. This feature can make any text in your report dynamic. For example, if you are on the account detail page, to display the report tile as Account detail for <account_number> instead of the default text, define the report title as a .vm resource bundle. In the following example, accountNumber is from the Struts ActionForm:

rpt.accountDetail.title=Account detail for $form.accountNumber