bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Internationalization Guide

Using Message Catalogs with BEA WebLogic Server

The following sections describe message catalogs and how to use them:

- Overview of Message Catalogs

- Message Catalog Hierarchy

- Choosing Names for Message Catalogs

- Using Message Arguments

- Message Catalog Formats

Overview of Message Catalogs

Message catalogs are XML files that contain a description of a collection of text messages, each indexed by a unique idenifier. You compile these XML files into classes during the i18ngen utility build process. (Refer to 18ngen Utility for more information). The methods of the resulting classes are the objects used to log messages at runtime.

Message catalogs support multiple locales or languages. For a specific message catalog there is exactly one default version, known as the top-level catalog. Then there are corresponding locale-specific catalogs, one for each additional supported locale. The top-level catalog includes all the information necessary to define the message. The locale-specific catalogs contain only the message ID, the date changed, and the translation of the message for the specific locale.

The message catalog files are defined by an XML document type definition (DTD). The DTDs are stored in the msgcat directory. The location of the msgcat directory may vary, depending upon where you installed WebLogic Server. If you used the default installation path, the msgcat directory is located in the BEA_HOME directory under WL_HOME\samples\server\src\examples\i18n\msgcat.

Two DTDs are included in the WebLogic Server distribution:

- msgcat.dtd—Describes the syntax of top-level, default catalogs.

- l10n_msgcat.dtd—Describes the syntax of locale-specific catalogs.

The msgcat directory also contains templates that you can use to create top-level and locale-specific message catalogs.

Users may choose to create a single log message catalog for all their logging requirements, or create smaller catalogs based on a subsystem or Java package. We recommend using multiple subsystems because you can focus on specific portions of the log during viewing.

For simple text catalogs, the recommended approach is to create a single catalog for each utility being internationalized. Developers can create site-specific message catalogs using the Message Editor as described in Using the BEA WebLogic Server Message Editor.

Message Catalog Hierarchy

All messages and exceptions must be defined in the default, top-level catalog. The WebLogic Server distribution includes a collection of sample catalogs in the WL_HOME\samples\server\src\examples\i18n\msgcat directory.

Note: This directory path may vary, depending on where you chose to install WebLogic Server.

Catalogs that provide different localizations of the base catalogs are defined in msgcat subdirectories named for the locale (for example, msgcat\de for Germany). You might have a top-level catalog named mycat.xml, and a German translation of it called ..\de\mycat.xml. Typically the top-level catalog is English, but English is not required for any catalogs except the installed WebLogic Server catalogs.

Locale designations (for example, de) also have a hierarchy as defined in the java.util.Locale documentation. A locale can include a language, country, and variant. Language is the most common locale designation. Language can be extended with a country code. For instance, en\US, indicates American English. The name of the associated catalog is ..\en\US\mycat.xml. Variants are vendor or browser-specific and are used to introduce minor differences (for example, collation sequences) between two or more locales defined by either language or country.

Choosing Names for Message Catalogs

Because the name of a message catalog file (without the .xml extension) is used to generate runtime class and property names, you should choose the name carefully.

Follow these guidelines for naming message catalogs:

- Do not choose a message catalog name that conflicts with any names of existing classes in the target package.

- The message catalog name should only contain characters that are allowed in class names.

- Follow class naming standards.

For example, the resulting class names for a catalog named Xyz.xml are XyzLogLocalizer and XyzLogger.

The following considerations also apply to message catalog files:

- Message IDs are generally six-character strings with leading zeros. Some interfaces also support integer representations.

- Java allows you to group classes into a collection called a package. A package name should be consistent with the name of the subsystem in which a particular catalog resides.

- The log Localizer "classes" are actually ResourceBundle property files.

Using Message Arguments

The message body, message detail, cause, and action sections of a log message can include message arguments, as described by java.text.MessageFormat. Only the message body section in a simple message can include arguments. Arguments are values that can be dynamically set at runtime. These values are passed to routines, such as printing out a message. A message can support up to 10 arguments, numbered 0-9. You can include any subset of these arguments in any text section of the message definition, although the message body should include all of the arguments. You insert message arguments into a message definition during development, and these arguments are replaced by the appropriate message content at runtime when the message is logged.

The following excerpt from an XML log message definition shows how you can use message arguments. The argument number must correspond to one of the arguments specified in the method attribute. Specifically, {0} with the first argument, {1} with the second, and so on.

Listing 2-1 Example of Message Arguments

>     <messagebody>Unable to open file, {0}.</messagebody>
>          <messagedetail>
>          File, {0} does not exist. The server will restore the file
>          contents from {1}, resulting in the use of default values
>          for all future requests.
>          </messagedetail>
>          <cause>The file was deleted</cause>
>          <action>
>          If this error repeats then investigate unauthorized access to
>          the file system.
>          </action>

An example of a method attribute for the above message is as follows:

>     -method="logNoFile(String name, String path)"

The message expects two arguments, {0} and {1}:

- {0} is used in the message body.

- Both are used in the message detail.

- Neither is used in the <cause> or <action> section.

In addition, the arguments are expected to be strings, or representable as strings. Numeric data is represented as {n,number}. Dates are supported as {n,date}. You must assign a severity level for log messages. Log messages are generated through the generated Logger methods, as defined by the method attribute.

Message Catalog Formats

The catalog format for top-level and locale-specific catalog files is slightly different. The top-level catalogs define the textual messages for the base locale. Locale-specific catalogs only provide translations of text defined in the top-level version. Log message catalogs are defined differently from simple text catalogs.

Elements of each of these types of catalogs are described in the following sections:

- Elements of a Log Message Catalog

- Elements of a Simple Text Message Catalog

- Elements of a Locale-Specific Catalog

Elements of a Log Message Catalog

This section provides reference information for the following elements of a log message catalog:

- message_catalog

- log_message

- Other log_message Catalog Elements

message_catalog

The following table describes the attributes that you can define for the message_catalog element.

Attribute | Default | Required/ Optional | Description
--- | --- | --- | ---
i18n_package | weblogic.i18n | Optional | Java package containing generated Logger classes for this catalog. The classes are named after the catalog file name. For example, for a catalog using mycat.xml, a generated logger class called i18n_package.mycatLogger.class.
l10n_package | weblogic.i18n | Optional | Java package containing generated LogLocalizer properties for this catalog. Classes are named after the catalog file name. For example, for a catalog called mycat.xml a properties file called l10n_package.mycatLogLocalizer. properties is generated.
subsystem | None | Required | An acronym identifying the subsystem associated with this catalog. The name of the subsystem is included in the error log and is used for message isolation purposes.
version | None | Required | Specifies the version of the msgcat.dtd being used. The format is n.n, for example, version="1.0". Must be at least "1.0".
baseid | 000000 for WebLogic Server catalogs 500000 for user-defined catalogs | Optional | Specifies the lowest message ID used in this catalog. The syntax is one to six decimal units.
endid | 499999 for WebLogic Server catalogs 999999 for user-defined catalogs | Optional | Specifies the highest message ID used in this catalog. The syntax is one to six decimal units.

log_message

The following table describes the attributes that you can define for the log_message element.

Attribute | Default | Required/ Optional | Description
--- | --- | --- | ---
messageid | None | Required | Unique identifier for this log message. Uniqueness should extend across all catalogs. Value must be in range defined by baseid and endid attributes. This is a child element of message_catalog.
datelastchanged | None | Optional | Date/time stamp used for managing modifications to this message. The date is supplied by utilities that run on the catalogs. The syntax is: Long.toString(new Date().getTime());
severity | None | Required | Indicates the severity of the log message. Must be one of the following: debug, info, warning, notice, error, critical, alert, or emergency. User catalogs may only use debug, info, warning, and error.
stacktrace | true | Optional | Indicates whether to generate a stack trace for Throwable arguments. Possible values are true or false. When the value is true a trace is generated. The syntax is: stacktrace="true"
method | None | Required | Method signature for logging this message. Two methods are actually provided: the one specified here and a similar one with an additional Throwable argument. The syntax is the standard Java method signature, without the qualifiers, semicolon, and extensions. Argument types can be any Java primitive or class. Classes must be fully qualified if not in java.lang. Classes must also conform to java.text.MessageFormat conventions. In general, class arguments should have a useful toString() method. Arguments can be any valid name, but should follow the convention of argn where n is 0 thru 9. There can be no more than ten (10) arguments. For each argn there should be at least one corresponding placeholder in the text elements described inOther log_message Catalog Elements Placeholders are of the form {n}, {n,number} or {n,date}.
loggables | False | Optional | Indicates whether to generate methods to return Loggable objects for each message. The syntax is: loggables="true" Refer to Loggable Object Reference for BEA WebLogic Server

Other log_message Catalog Elements

The following table describes the child elements of the log_message element.

Element | Parent Element | Required/ Optional | Description
--- | --- | --- | ---
messagebody | log_message | Required | A string containing a short description for this message. This element may contain zero or more placeholders, {n} that are replaced by the appropriate argument when the log message is localized.
messagedetail | log_message | Required | A string containing a detailed description of the event. This element may contain zero or more placeholders, {n} that are replaced by the appropriate argument when the log message is localized.
cause | log_message | Required | A string describing the root cause of the problem. This element may contain zero or more placeholders, {n} that are replaced by the appropriate argument when the log message is localized.
action | log_message | Required | A string describing the recommended resolution. This element may contain zero or more placeholders, {n} that are replaced by the appropriate argument when the log message is localized.

Log Message Catalog Example

The following example shows a log message catalog, MyUtilLog.xml, with one log message.

Listing 2-2 Example of a Log Message Catalog

>     <?xml version="1.0"?>
>     <!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"     "http://www.bea.com/servers/wls700/dtd/msgcat.dtd">
>     <message_catalog
>       l10n_package="programs.utils"
>       i18n_package="programs.utils"
>       subsystem="MYUTIL"
>       version="1.0"
>       baseid="600000"
>       endid="600100"
>       <log_message
>         messageid="600001"
>         severity="warning"
>         method="logNoAuthorization(String arg0, java.util.Date arg1,
>            int arg2)"
>         <messagebody>
>           Could not open file, {0} on {1,date} after {2,number} attempts.
>         </messagebody>
>         <messagedetail>
>           The configuration for this application will be defaulted to
>           factory settings. Custom configuration information resides
>           in file, {0}, created on {1,date}, but is not readable.
>         </messagedetail>
>         <cause>
>           The user is not authorized to use custom configurations. Custom
>          configuration information resides in file, {0}, created on
>          {1,date}, but is not readable.The attempt has been logged to
>          the security log.
>         </cause>
>         <action>
>           The user needs to gain approriate authorization or learn to
>           live with the default settings.
>         </action>
>       </log_message>
>     </message_catalog>

Elements of a Simple Text Message Catalog

This section provides reference information for the following simple text message catalog elements:

- message_catalog

- message

- messagebody

message_catalog

The following table describes the attributes that you can define for the message_catalog element.

Attribute | Default | Required/ Optional | Description
--- | --- | --- | ---
l10n_package | weblogic.i18n | Optional | Java package containing generated TextFormatter classes and TextLocalizer properties for this catalog. Classes are named after the catalog file name. For example, for a catalog called mycat.xml, a properties file called l10n_package.mycatTextLocalizer properties is generated.
subsystem | None | Required | An acronym identifying the subsystem associated with this catalog. The name of the subsystem is included in the error log and is used for message isolation purposes.
version | None | Required | Specifies the version of the msgcat.dtd being used. The format is n.n, for example, version="1.0". Must be at least "1.0".

message

The following table describes the attributes that you can define for the message element.

Attribute | Default | Required/ Optional | Description
--- | --- | --- | ---
messageid | None | Required | Unique identifier for this log message in alpha-numeric string format. Uniqueness is required only within the context of this catalog. message is a child element of message_catalog.
datelastchanged | None | Optional | Date/time stamp useful for managing modifications to this message.
method | None | Optional | Method signature for formatting this message. The syntax is a standard Java method signature, less return type, qualifiers, semicolon, and extensions. The return type is always String. Argument types can be any Java primitive or class. Classes must be fully qualified if not in java.lang. Classes must also conform to java.text.MessageFormat conventions. In general, class arguments should have a useful toString() method, and the corresponding MessageFormat placeholders must be strings; they must be of the form {n}. Argument names can be any valid name. There can be no more than 10 arguments. For each argument there must be at least one corresponding placeholder in the messagebody element described below. Placeholders are of the form {n}, {n,number} or {n,date}. Example: method="getNoAuthorization (String filename, java.util.Date creDate)" This example would result in a method in the TextFormatter class as follows: public String getNoAuthorization (String filename, java.util.Date creDate)

messagebody

The following table describes the child element of the message element.

Element | Parent Element | Required/ Optional | Description
--- | --- | --- | ---
messagebody | message | Required | The text associated with the message. This element may contain zero or more placeholders {n} that will be replaced by the appropriate arguments when the log message is localized.

Simple Text Catalog Example

The following example shows a simple text catalog, MyUtilLabels.xml, with one text definition.

Listing 2-3 Example of a Simple Text Catalog

>     <?xml version="1.0"?>
>     <!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
>         "http://www.bea.com/servers/wls700/dtd/msgcat.dtd">
>     <message_catalog>
>      l10n_package="programs.utils"
>      i18n_package="programs.utils"
>      subsystem="MYUTIL"
>      version="1.0"
>      <message>
>       messageid="FileMenuTitle"
>       <messagebody>
>         File
>       </messagebody>
>      </message>
>     </message_catalog>

Elements of a Locale-Specific Catalog

The locale-specific catalogs are subsets of top-level catalogs. They are maintained in subdirectories named for the locales they represent. The elements and attributes described in the following sections are valid for locale-specific catalogs.

locale_message_catalog

The following table describes the attributes that you can define for the locale_message_catalog element.

Attribute | Default | Required/ Optional | Description
--- | --- | --- | ---
l10n_package | weblogic.i18n | Optional | Java package containing generated LogLocalizer or TextLocalizer properties for this catalog. properties are named after the catalog file name. For example, for a French log message catalog called mycat.xml, a properties file called l10n_package.mycatLogLocalizer_fr_ FR.properties properties is generated.
version | None | Required | Specifies the version of the msgcat.dtd being used. The format is n.n, for example, version="1.0". Must be at least "1.0".

log_message

The locale-specific catalog uses the attributes defined for the log_message element in the log message catalog so this element does not need to be defined.

Other locale_message_catalog Elements

The locale-specific catalog uses the messagebody, messagedetail, cause, and action catalog elements defined for the log message catalog so these elements do not need to be defined.

Locale Message Catalog Syntax

The following example shows a French translation of a message that is available in ...\msgcat\fr\MyUtilLabels.xml.

The translated message appears as shown in Listing 2-4.

Listing 2-4 Example of a Message Translated to French

>     <?xml version="1.0"?>
>     <!DOCTYPE message_catalog PUBLIC
>        "weblogic-locale-message-catalog-dtd"
>        "http://www.bea.com/servers/wls700/dtd/l10n_msgcat.dtd">
>     <locale_message_catalog
>       l10n_package="programs.utils"
>       subsystem="MYUTIL"
>       version="1.0">
>       <message>
>         <messageid="FileMenuTitle">
>         <messagebody> Fichier </messagebody>
>       </message>
>     </locale_message_catalog>

When entering text in the messagebody, messagedetail, cause and action elements, you must use a tool that generates valid Unicode Transformation Format-8 (UTF-8) characters, and have appropriate keyboard mappings installed. UTF-8 is an efficient encoding of Unicode character-strings that optimizes the encoding ASCII characters. Message catalogs always use UTF-8 encoding. The MessageLocalizer utility that is downloaded with WebLogic Server is a tool that can be used to generate valid UTF-8 characters.