Using the BEA WebLogic Server Internationalization Utilities

Using the BEA WebLogic Server Internationalization Utilities

The following sections contain information about the WebLogic Server utilities used for internationalization and localization:
WebLogic Server Internationalization Utilities
WebLogic Server Internationalization and Localization
weblogic.i18ngen Utility
weblogic.l10ngen Utility
weblogic.GetMessage Utility

WebLogic Server Internationalization Utilities

WebLogic Server provides three internationalization utilities:
weblogic.i18ngen Utility - Message catalog parser. Use this utility to validate and generate classes used for localizing text in log messages. For more information, see weblogic.i18ngen Utility.
weblogic.l10ngen Utility - Locale-specific message catalog parser. Use this utility to process locale-specific catalogs. For more information, see weblogic.l10ngen Utility.
weblogic.GetMessage Utility - Utility that lists installed log messages. Use this utility to generate a list of installed log messages or display a message. For more information, see weblogic.GetMessage Utility.

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.
Note: Use escapes to embed newlines (for example '\n'). These are stored and result in newlines when printed.

WebLogic Server Internationalization and Localization

Use the weblogic.i18ngen utility to validate message catalogs and create the necessary runtime classes for producing localized messages. The weblogic.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 configure the applications with Logger and TextFormatter classes generated from the weblogic.i18ngen utility.
Refer to weblogic.i18ngen Utility for detailed information about the weblogic.i18ngen utility. For more information on Logger and TextFormatter classes, refer to TextFormatter Class Reference for BEA WebLogic Server, and Logger Class Reference for BEA WebLogic Server.
The generated Logger classes are used for logging purposes instead of the traditional method of writing English text to a log. For example, weblogic.i18ngen generates a class xyzLogger in the appropriate package for the catalog xyz.xml. For example, for the MyUtilLog.xml catalog, the class programs.utils.MyUtilLogger.class wouldbe generated. For each log message defined in the catalog, this class contains static public methods as defined by the method attributes.
TextFormatter classes are generated for each simple message catalog. These classes include 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.

weblogic.i18ngen Utility

Use the weblogic.i18ngen utility to parse message catalogs (XML files) to produce Logger and TextFormatter classes used for localizing the text in log messages. The utility creates or updates the following properties file (which is used to load the message id lookup class hashtable weblogic.i18n.L10nLookup):
targetdirectory/i18n_user.properties 
The weblogic.i18ngen utility also creates or updates the i18n_user.properties file. Any errors, warnings, or informational messages are sent to stderr.
In order for user catalogs to be recognized, the i18n_user.properties file must reside in a directory identified in the WebLogic classpath.
For example:
targetdirectory/i18n_user.properties
BEA recommends that the i18n_user.properties file reside in the server classpath. If the i18n_user.properties file is in targetdirectory, then targetdirectory should be in the server classpath.

Syntax
java weblogic.i18ngen [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

Option

Definition
-build
Generates all necessary files and compiles them.The -build option combines the -i18n, -l10n, -keepgenerated, and -compile options.
-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. This directory is created as necessary.If this argument is omitted, all classes are generated in the current directory, without regard to any class hierarchy described in the message catalog.
-n Parse and validate, but do not generate classes.
-keepgenerated Keep generated Java source (located in the same directory as the class files).
-ignore Ignore errors.
-i18n Generates internationalizers (for example, Loggers and TextFormatters).i18ngen -i18n creates the internationalizer source (for example, *Logger.java) that supports the logging of internationalized messages.
-l10n Generates localizers (for example, LogLocalizers and TextLocalizers).i18ngen -l10n creates the localizer source (resource bundles) that provide access to each message defined in the message catalog. These classes 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. The resulting classes are placed in the same directory as the source. 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.
-debug Debugging mode.
-dates Causes weblogic.i18ngen to update message timestamps in the catalog. If the catalog is writeable and timestamps have been updated, the catalog is rewritten.
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. weblogic.i18ngen prints the fully-qualified list of names (Java source) to the stdout log for those files actually generated.

weblogic.l10ngen Utility

The weblogic.l10ngen utility generates property resources for localizations of message catalogs named in the filelist. The file list identifies the top-level catalogs, not translated catalogs.
Similarly the target directory (-d option) identifies the same target directory where the default localizations reside. For example, if the default catalogs are located in $SRC/weblogic/msgcat and the generated resources are to be placed in $CLASSESDIR, the appropriate l10ngen invocation would be:
java weblogic.i18n.tools.l10ngen -d $CLASSESDIR $SRC/weblogic/msgcat
This command generates localized resources for all locales defined in the weblogic/msgcat subdirectories.

Syntax
java weblogic.l10ngen [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

Option

Definition
-d target 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 Specifies the message catalogs for which you want to generate properties files. You must specify top-level catalogs that the Message Editor creates; you do not specify locale-specific catalogs that the Message Localizer creates. Usually this is the same set of source files or source directories that you specified in the i18ngen command.

Message Catalog Localization

Catalog subdirectories are named after lowercase, two-letter ISO 639 language codes (for example, ja for Japanese and fr for French). You can find supported language codes in the java.util.Locale javadoc.
Variations to language codes are achievable through the use of uppercase, two-letter ISO 3166 country codes and variants, each of which are subordinate to the language code. The generic syntax is lang/country/variant.
For example, zh is the language code for Chinese. CN is a country code for simplified Chinese, whereas TW is the country code for traditional Chinese. Therefore zh/CN and zh/TW are two distinct locales for Chinese.
Variants are of use when, for instance, there is a functional difference in platform vendor handling of specific locales. Examples of vendor variants are WIN, MAC and POSIX. There may actually be two variants used to further qualify the locale. In this case, the variants are separated with an underscore (for example, Traditional_Mac vs. Modern_MAC).
Note: Language, country and variants are all case sensitive.
A fully-qualified locale would look like zh/TW/WIN, identifying traditional Chinese on a Win32 platform.
Message catalogs to support the above locale would involve the following files:
/*.xml - default catalogs
/zh/*.xml - Chinese localizations
/zh/TW/*.xml - Traditional Chinese localizations
/zh/TW/WIN/*.xml - Traditional Chinese localizations for Win32 code sets

Specific localizations do not need to cover all messages defined in parent localizations.

Examples
To generate localization properties for all locales:
java weblogic.i18ntools.l10ngen -d $CLASSESEDIR catalogdirectory
To generate localization properties for all traditional Chinese locales:
java weblogic.i18ntools.l10ngen -d $CLASSESEDIR -language zh -country TW catalogdirectory
To generate localization properties for all Chinese locales:
java weblogic.i18ntools.l10ngen -d $CLASSESEDIR -language zh catalogdirectory
To generate localization properties for the JMS catalog in all locales:
java weblogic.i18ntools.l10ngen -d $CLASSESEDIR catalogdirectory
Note: Example 2 is a subset of example 3. All Chinese (zh) would include any country designations (for example, TW) and variants.
weblogic.l10ngen does not validate the locale designators (language, country, variant).

weblogic.GetMessage Utility

The weblogic.GetMessage utility replaces the CatInfo utility provided with earlier releases of WebLogic Server. This utility displays message content but can also be used to list all or some subset of installed messages. By default (no options), weblogic.GetMessage prints a usage statement.

Syntax
java weblogic.GetMessage [options]
Options

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

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.
-nodetail Requests a non-detailed listing, and only outputs the message body of a message.By default, a detailed listing is output, which includes severity, subsystem, message detail, cause, and action information.
-verbose Requests more detail on the listing. The -verbose option also prints packaging, stacktrace option, severity, subsystem, message detail, cause, and action information.
-lang code The language to use. For example, en for English.
-country code The country code to use. For example, US for United States.
-variant code The variant designator for locale.
-help Provides usage information.
-retired Lists all retired messages. Retired messages are not displayed unless this option is used. Only the subsystem and id's of such messages are listed.

If no arguments are provided, weblogic.GetMessage outputs a usage message, equivalent to -help.

Option	Definition
-build	Generates all necessary files and compiles them.The -build option combines the -i18n, -l10n, -keepgenerated, and -compile options.
-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. This directory is created as necessary.If this argument is omitted, all classes are generated in the current directory, without regard to any class hierarchy described in the message catalog.
-n	Parse and validate, but do not generate classes.
-keepgenerated	Keep generated Java source (located in the same directory as the class files).
-ignore	Ignore errors.
-i18n	Generates internationalizers (for example, Loggers and TextFormatters).i18ngen -i18n creates the internationalizer source (for example, *Logger.java) that supports the logging of internationalized messages.
-l10n	Generates localizers (for example, LogLocalizers and TextLocalizers).i18ngen -l10n creates the localizer source (resource bundles) that provide access to each message defined in the message catalog. These classes 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. The resulting classes are placed in the same directory as the source. 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.
-debug	Debugging mode.
-dates	Causes weblogic.i18ngen to update message timestamps in the catalog. If the catalog is writeable and timestamps have been updated, the catalog is rewritten.
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. weblogic.i18ngen prints the fully-qualified list of names (Java source) to the stdout log for those files actually generated.

Option	Definition
-d target	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	Specifies the message catalogs for which you want to generate properties files. You must specify top-level catalogs that the Message Editor creates; you do not specify locale-specific catalogs that the Message Localizer creates. Usually this is the same set of source files or source directories that you specified in the i18ngen command.

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.
-nodetail	Requests a non-detailed listing, and only outputs the message body of a message.By default, a detailed listing is output, which includes severity, subsystem, message detail, cause, and action information.
-verbose	Requests more detail on the listing. The -verbose option also prints packaging, stacktrace option, severity, subsystem, message detail, cause, and action information.
-lang code	The language to use. For example, en for English.
-country code	The country code to use. For example, US for United States.
-variant code	The variant designator for locale.
-help	Provides usage information.
-retired	Lists all retired messages. Retired messages are not displayed unless this option is used. Only the subsystem and id's of such messages are listed.