1.) Internationalizing EspressReport

EspressReport provides many different features that enable you to generate reports for just about any locale and language.  Different internationalization features can require different system or setting configurations depending on your specific requirements.

1.1.) Specifying Locales

EspressReport allows reports and charts to have different timezones and locales.  They are not limited to the locale on the machine where they are created.  The locale can be set through the API immediately before the report or chart is run.

1.1.1.) Locale-specific Formatting

For data formatting (date and numeric), EspressReport allows you to set locale-specific formatting for report elements.  Locale-specific formatting allows data elements to be displayed in the correct format for the particular locale that is being used for the report.  Locale-specific options are available in the data formatting dialog for Report Designer (see section 5.7.3 of the Designer Guide).

The locale for report and charts, as well as the time zone can be set at run-time through the API.  Note that this only effects the date and time, as well as the data formatting.

1.1.2.) Setting Timezones and Locales Using the API

To set the timezone or locale, you can use the methods in QbReport/QbChart (applies to the entire report/chart) or use LocaleDateTimeFormat and LocaleNumericFormat objects (applies to a specific object in the report/chart).  The following code fragments show how to do this with the two different approaches.

report.setLocale(Locale.UK);
report.setTimeZone(TimeZone.getTimeZone("GMT"));

Full Source Code
Report Template
Exported Results

Here the formats are applied to the entire report.  Alternatively, you can apply the format to specific data columns as follows:

LocaleNumericFormat currencyFormat = LocaleNumericFormat.getCurrencyInstance();
currencyFormat.setLocale(Locale.UK);
int columnIndex = 2; //column 2 is the "Unit Price" column
report.getTable().getColumn(columnIndex).setDataFormat(currencyFormat);

LocaleDateTimeFormat dateFormat = LocaleDateTimeFormat.getDateInstance();
dateFormat.setTimeZone(TimeZone.getTimeZone("GMT"));
report.getPageFooter().getData(1).setDataFormat(dateFormat);

Full Source Code
Report Template
Exported Results

1.2.) Language and Encoding

EspressReport includes a set of features that removes limitations caused by language differences.  By utilizing a simple to use interface, it is possible to translate all the text, buttons, and menus within EspressReport to a different language.  Through some basic configuration, you will be able to import, view, and type characters in a foreign language as well as save and export reports in that language.

1.2.1.) EspressReport Language Translation

Internationalization is supported through the use of an .xml file, Language.xml (located in the <EspressReport installation directory>).  A GUI is provided to work with the Language.xml file and replace the lines of English with those of another language.

The Language.xml file has the following structure:

<Product name="REPORTDESIGNER" dir="quadbase/reportdesigner/designer">
<File name="ReportMenubar.java">
<CODE>File</CODE>
<TEXT>File</TEXT>
<CODE>New</CODE>
<TEXT>New</TEXT>
...
</File>
</Product>

The file has the following tree structure: Product (Directory) -> File -> text.  You can easily search the product, file, or text you want to translate and simply replace the Text between <Text> and </Text> with the translation.  EspressReport will replace <Code> with <Text> in the Java Swing UI and/or in the EspressReport web application.   The translation GUI will list all the products and each product will list the codes that need translation.  A same code, (for example, "File") may be listed under several products to maintain the completeness of each product.   However, the translation for a code is duplicated across all products.  The same code cannot have two different translations for different products.

The Language.xml file is located in the install directory.  It is recommended that you make a copy (of Language.xml) and then use the GUI provided (on the copy) to put in the translation without touching the xml file directly.  To utilize the user interface, navigate to the EspressReport root directory and enter the following command:

java -classpath "./lib/ReportAPIWithChart.jar;.;" quadbase.internationalization.TranslateWizard -file:<fileName> -enc:<encoding>

where <fileName> represents the xml file that will store the translation and <encoding> represents the encoding for the translation.  For correct results, the proper encoding must be specified.  If the file name and encoding are not provided, the default file name (Language.xml) and default encoding (Cp1252) will be used.

An example of the above command is given below:

java -classpath "./lib/ReportAPIWithChart.jar;.;" quadbase.internationalization.TranslateWizard -file:Chinese.xml -enc:Big5

Where Big5 is the encoding used to save Chinese.xml file.

When the translation wizard is started, it appears as below:

Translate Wizard

You can see the various codes (available for translation) by selecting appropriate Product.  Products are shown in a tree on the left that contains all the files available for translation.  For example, on the image below you can see expanded "QUERYBUILDER" product.  You may either translate entire product by selecting the product node or just select a file that you want to translate.

Insert Translation

The English texts are listed on the left and you can enter the translation on the right.  The translation can be entered by clicking on the cell and typing in the text.  The translation can be saved (to the file specified by the command that started the wizard) by clicking on the "SAVE" button.  You can navigate to the previous screen by clicking on the "PREVIOUS" button.  Note that if a translation for a code has already been set, it will appear for every instance of the code.

Note that more options exist in the Translate Wizard than is required by EspressReport. For example, the ORGANIZER product does not exist in EspressReport and hence any changes made in this product will not show up.

You can use Language.xml (or the copy you modified) in EspressReport by adding the -file and -enc arguments to the java application or java applet that starts EspressManager, Report Designer and/or Scheduler.

1.2.1.2.) Upgrading Language File

When the user upgrades to a newer version, the Language.xml file needs to be upgraded as well.  The language upgrade program will copy over the translations from the previously customized Language.xml file and append the additional entries in the new version.  To use the language upgrade program, navigate to the ER directory from a console window and use the following command.

java -classpath ".;.\lib\ReportAPIWithChart.jar" quadbase.internationalization.UpgradeLanguageXMLFile -from:oldfile -to:newfile -enc:encoding

It may be necessary replace the semicolon with colon and backslash with slash on non-Window environments.

Oldfile refers to the customized Language.xml from a previous version of ER, newfile refers to the Language.xml included in the upgraded ER installation, and the enc is the language encoding used in the translation.  After running the program, the resulting file will be named Language.xml and you can open it with TranslateWizard to further translate any new entries.

1.2.2.) Displaying Foreign Characters

Foreign characters can easily be displayed in Designer and the various Viewers.  To display foreign characters in a report/chart, you will need to have fonts for that language present on the system.  Then, in the report/chart, you can set the font for the object that contains foreign characters to the appropriate system font.

The other option is to modify the font.properties file in the JVM so that foreign characters are supported in the default JVM fonts.  For Sun JVMs, the font.properties file is located under the jre/lib directory.  The different language files have names like font.properties.ru for Russian, font.properties.zh for Chinese, etc.  To change the language settings for the JVM, rename the current font.properties file to back it up, and change the name of the desired language file to "font.properties".  With the language settings changed in the JVM, the default fonts in EspressReport (Dialog, Serif, Monospaced, etc.) will display with foreign characters.

1.2.3.) Entering Foreign Characters

In order to enter foreign characters into any of the EspressReport interfaces (for example, Report Designer), the following changes to the system settings are required:

• The default locale of your system must be set to the region for the language you would like to use.
• The input locale for the system must also be set to the region for the language you would like to use

Note that for Windows the settings can be accessed through Regional Options in the Control Panel.

In addition, the font settings in the JVM must be adjusted to the desired language following the instructions discussed in section 1.2.2.

Once these settings have been applied, foreign characters can be entered in labels, queries, formulas, and parameters in reports/charts.

1.2.4.) XML Encoding

By default, EspressReport uses the UTF-8 character set for encoding when writing to XML.  This includes the data registry files, XML report templates, the XML exports, as well as the XML representations of global format information, and font mapping.  Please note that for most of users it is not necessary to change character set encoding, because UTF-8 fully supports all languages.

This encoding can be changed for other languages by adding a run-time parameter to Report Designer and EspressManager.  For Report Designer, you can do this by modifying the reportdesigner.bat/sh file, or modifying the applet page used to launch the Report Designer.

To change the XML encoding, add the following argument to the <EspressReportInstallDir>\reportdesigner.bat or .sh file: -xmlEncoding:Encoding.  For example -xmlEncoding:ISO-2022-JP would set the encoding for the Japanese character set.

If you're running Report Designer through an applet, you will need to add the following parameter to the applet page: <PARAM NAME="xml_encoding" VALUE="ISO-2022-JP">.

This parameter also needs to be set for the server.  For more information about server settings, please see Starting EspressManager section.

1.2.5.) Exporting With Foreign Characters

Most of the EspressReport export formats will be automatically generated with the UTF-8 character encoding.  In order to view the exported reports/charts the client will need to have the appropriate system fonts installed.  The only exception to this is the PDF export.  PDF format does not depend on client fonts for viewing and foreign language fonts will need to be embedded into the PDF document, in order for characters to display properly.  To do this, you will need to use the PDF Font Mapping feature.  Font Mapping can be set in Designer and in API.

If you wish to export the report/chart to a locale different from the one that is set on the machine, you can specify a different encoding before doing the export.  This is done using the following method in QbReport:

public void setExportEncoding(String encoding);

where encoding is a character encoding supported by the Java 2 platform.  For example, the character encoding for English (Windows Latin-1) is Cp1252.  Please note that you have to use the canonical name used by the java.io and java.lang API's.

You can also specify the character set used in the HTML and DHTML exports, using the following method in QbReport:

public void setHTMLCharSet(String charset);

where charset is a valid character set.  For example, a character set for English, used in HTML/DHTML documents, is UTF-8.

Full Source Code
Report Template
Exported Results

1.2.6.) Specifying Encoding for Text Data Files

By default, EspressReport uses Western European encoding for any text data files.  The encoding for input text data files can be set via the API by using the following block of code:

report.getInputData().setDataFile("../data/sample.dat", false, "ASCII");

Full Source Code
Report Template
Exported Results

The above block uses the following method found in quadbase.reportdesigner.util.IInputData:

public void setDataFile(String fileName, boolean isDataSorted, String encoding);