bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Internationalization Guide

Using the BEA WebLogic Server Internationalization Utilities

The following sections contain information about the WebLogic Server utilities used for internationalization and localization:

- About the WebLogic Server Internationalization Utilities

- About the WebLogic Server Internationalization and Localization Interfaces

- 18ngen Utility

- l10ngen Utility

- CatInfo Utility

About the WebLogic Server Internationalization Utilities

WebLogic Server provides three internationalization utilities:

- 18ngen Utility—Message catalog parser. Use this utility to generate classes used for localizing text in log messages.

- l10ngen Utility—Locale-specific message catalog parser. Use this utility to process locale-specific catalogs.

- CatInfo Utility—Utility that lists installed log messages. Use this utility to generate a list of installed log messages.

Note: Text in the catalog definitions may contain formatting characters for readability (for example, end of line characters), but these are not preserved by the parsers. Text data is normalized into a one-line string. All leading and trailing white space is removed. All embedded end of line characters are replaced by spaces as required to preserve word separation. Tabs are left intact.

About the WebLogic Server Internationalization and Localization Interfaces

The i18ngen utility validates message catalogs, creating the necessary runtime classes for producing localized messages. The l10ngen utility validates locale-specific catalogs, creating additional properties files for the different locales defined by the catalogs.

You can internationalize simple text-based utilities that you are running on WebLogic Server by specifying that those utilities must use Localizers to access text data. You instument the applications with Logger and TextFormatter classes generated from the i18ngen utility. Refer to 18ngen Utility for detailed information about the i18ngen utility.

The generated Logger classes are used for logging purposes instead of the traditional method of writing English text to a log. For example, i18ngen generates a class xyzLogger in the appropriate package for the catalog xyz.xml.

As another example, when the MyUtilLog.xml catalog is used, the class programs.utils.MyUtilLogger.class is generated. For each log message defined in the catalog, this class contains static public methods as defined by the method attribute.

TextFormatter classes are generated for each simple message catalog. These classes include static methods for accessing localized and formatted text from the catalog. They are convenience classes that handle the interface with the message body, placeholders, and MessageFormat. You specify the formatting methods through the method attribute in each message definition. For example, if the definition of a message in a catalog includes the attribute, method=getErrorNumber(int err), the TextFormatter class shown in Listing 4-1is generated.

Listing 4-1 Example of a TextFormatter Class

>     package my.text;
>     public class xyzTextFormatter
>     {
>        . . .
>        public String getErrorNumber(int err)
>        {
>        . . .
>        }
>     }

Listing 4-2 shows an example of how the getErrorNumber method could be used in code.

Listing 4-2 Example of getErrorNumber Method

>     import my.text.xyzTextFormatter
>     . . .

>     xyzTextFormatter xyzL10n = new xyzTextFormatter();
>     System.out.println(xyzL10n.getErrorNumber(someVal));

The output prints the message text in the current locale, with the someVal argument inserted appropriately.

18ngen Utility

The i18ngen utility parses message catalogs (XML files) to produce Logger and TextFormatter classes used for localizing the text in log messages. The top-level message catalogs are compiled into Java classes and properties files. The i18ngen utility also creates or updates the i18n_user.properties file. Any errors, warnings, or informational messages are sent to stderr.

Syntax

>     java weblogic.i18ngen [options] files

Note: Utilities can be run from any directory, but if files are listed on the command line, then their path is relative to the current directory.

Options

Option | Definition
-d targetdirectory | Specifies the root directory to which generated Java source files are targeted. User catalog properties are placed in i18n_user.properties, relative to the designated target directory. Files are placed in appropriate directories based on the i18n_package and l10n_package values in the corresponding message catalog. The default target directory is the current directory.
-n | Parse and validate, but do not generate classes
-keepgenerated | Keep generated Java source
-ignore | Ignore errors
-i18n | Creates the internationalizer source (for example, *Logger.java) that supports the logging of internationalized messages.
-l10n | Creates the localizer source (property resource bundles) that provides access to each message defined in each message catalog. These properties are used by localization utilities to localize messages.
-compile | Compiles generated Java files using the current CLASSPATH. The resulting classes are placed in the directory identified by the -d option. Errors detected during compilation generally result in no class files or properties file being created. i18ngen exits with a bad exit status.
-nobuild | Parse and validate only
files | Process the files and directories in this list of files. If directories are listed, the command processes all XML files in the listed directories. The names of all files must include an XML suffix. All files must conform to the msgcat.dtd syntax. i18ngen prints the fully-qualified list of names (Java source) to the stdout log for those files actually generated.

l10ngen Utility

The l10ngen utility processes the locale-specific catalogs in directories that are subordinate to the top-level catalogs.

Syntax

>     java -classpath <l10n_Classpath> weblogic.i18ntools.l10ngen [options] filelist

>     where <l10n_Classpath> should include <WebLogic Home>/lib/weblogic.jar

Note: Utilities can be run from any directory, but if files are listed on the command line, then their path is relative to the current directory.

Options

Option | Definition
-d targetdirectory | Directory in which to place properties. Default is the current directory.
-language code | Language code. Default is all.
-country code | Country code. Default is all.
-variant code | Variant code. Default is all.
-filelist | Message catalog directories and files to process, relative to the current directory. Identifies top-level, not local-specific, directory.

CatInfo Utility

This utility generates a listing of installed log messages. By default, CatInfo lists in order the ID and message body for all currently installed log messages.

Syntax

>     java weblogic.i18ntools.CatInfo [options]

Note: Utilities can be run from any directory, but if files are listed on the command line, then their path is relative to the current directory.

Options

Note: All options may be abbreviated to a single character.

Option | Definition
--- | ---
-id nnnnnn | where nnnnnn represents the message ID. The -id option is used to specify a particular message.
-subsystem identifier | The subsystem identifier. The -subsystem option prints only those messages that match the specified subsystem.
-detail | Requests a detailed listing. The -detail option also requests version, severity, subsystem, message detail, cause, and action information.
-help | Provides usage information.

To export the detailed list of messages to a file, use the following command:

>     java weblogic.i18ntools.CatInfo -detail > Errors.txt