Chapter 13. Internationalization

13.1. Internationalizing EspressChart

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

13.1.1. Specifying Locales

EspressChart allows different time zones and locales for charts. They are not limited to the locale on the machine on which they are created. The locale can be set through API right before the chart is run.

13.1.1.1. Locale-Specific Formatting

EspressChart allows you to set locale-specific formatting for chart elements, including date and numeric data. Locale-specific formatting allows data elements to be displayed in the correct format for the particular locale that is being used for the chart. Locale-specific options are available in the data formatting dialog for Chart Designer (see Section 6.7.2.1 - Axis Label Formatting).

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

13.1.1.2. Setting Time Zones and Locales Using the API

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

chart.setLocale(Locale.UK);
chart.settime zone(time zone.gettime zone("GMT"));
        

Full Source Code

Exported Results

Here the formats are applied to the entire chart. 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 "Sales" column
chart.gethDataPoints().setLabelFormat(columnIndex, currencyFormat);
        

Full Source Code

Exported Results

13.1.2. Language and Encoding

EspressChart 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 text, buttons, and menus within EspressChart 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 charts in that language.

13.1.2.1. EspressChart Language Translation

Internationalization is supported through the use of an .xml file, Language.xml (located in the <EspressChart 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="CHARTDESIGNER" dir="quadbase/chartdesigner/designer">

      <File name="ChartMenubar.java">
            <CODE>File</CODE>
            <TEXT>File</TEXT>
            <CODE>New</CODE>
            <TEXT>New</TEXT>
            ... </File> 

</Product>
        

The file has the following tree structure: Product (Directory)Filetext. 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. EspressChart will replace <Code> with <Text> in the Java Swing UI and/or in the EspressChart web application. The translation GUI will list all products and each product will list 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 EspressChart root directory and enter the following command:

java -classpath "./lib/EspressAPI.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/EspressAPI.jar;.;" quadbase.internationalization.TranslateWizard -file:Chinese.xml -enc:gbk
        

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

When the Translate 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 can 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 EspressChart. For example, the REPORTDESIGNER and ORGANIZER products do not exist in EspressChart and hence any changes made in those products will not show up.

You can use Language.xml (or the copy you modified) in EspressChart by adding the -file and -enc arguments to the java application or java JNLP (More about Applets in JNLP: Section 2.6 - Run Applets As JNLP) that starts EspressManager, ChartDesigner and/or Scheduler.

13.1.2.1.1. 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 EspressChart directory from a console window and use the following command:

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

It may be necessary to 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 EspressChart, newfile refers to the Language.xml included in the upgraded EspressChart 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 Translate Wizard to further translate any new entries.

13.1.2.2. Displaying Foreign Characters

Foreign characters can be easily displayed in Designer and Viewer. To display foreign characters in a chart, you will need to have fonts for that language installed in your system. Then, in the chart, you can set the font for the object that contains foreign characters to the appropriate system font.

Another 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 EspressChart (Dialog, Serif, Monospaced, etc.) will display with foreign characters.

13.1.2.3. Entering Foreign Characters

In order to enter foreign characters into any EspressChart interface (for example, ChartDesigner), 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 want to use.

  • The input locale for the system must also be set to the region for the language you want 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 13.1.2.2 - Displaying Foreign Characters.

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

13.1.2.4. XML Encoding

By default, EspressChart use UTF-8 character set for encoding when writing to XML. This includes data registry files, XML chart templates, XML exports, and 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 ChartDesigner and EspressManager. For ChartDesigner, you can do this by modifying the ChartDesigner.bat/sh file, or modifying the applet page used to launch the ChartDesigner.

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

If you are running ChartDesigner 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 Section 2.3 - Starting EspressManager.