Using the BEA WebLogic Server Internationalization Tools and Utilities

 

This section includes information about the following topics:

• Using the Message Editor

• Using the Internationalization Utilities

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

Using the Message Editor

The Message Editor is a GUI for editing XML message catalogs. It creates, reads, and writes XML catalogs. Optionally, you can also edit the XML catalogs directly, in a text editor. Message Editor allows you to perform the following tasks:

• Create XML message catalogs

• Create and edit messages

• View all the messages in one catalog

• View all the messages in several catalogs simultaneously

• Search for messages

• Validate the XML in catalog entries

The catalog current being created or used in the Message Editor is referred to as the context catalog.

The catalog parser recognizes special character references and converts them to the intended character, as shown in Table 4-1. The Message Editor will recognize the special characters and write them back using the character references. The parser recognizes no other character references.

Table 4-1 Special Character Reference

Character	Character Code
@	&
<	&lt;
>	&gt;
`	&apos;
"	&quot;

Starting the Message Editor

To start the Message Editor, type:

java weblogic.MsgEditor

The main Message Editor for a log message is displayed as follows:

When displaying a simple message catalog in the Message Editor, it will appear as follows:

Editing an ExistingCatalog

To edit an existing catalog:

• Enter the full pathname in the Message Catalog field, or click the Browse button and navigate to the existing catalog.

The catalogs can be found in the directory $SRC/weblogic/msgcat. Once the catalog has been located, the packages, subsystem, version and base id and end id (if any) for that catalog are displayed, and that catalog is the catalog context in which all other actions are performed. You are now ready to enter new messages into that catalog, to edit existing messages, to search for a message, or to view all messages in the catalog.

Creating a New Catalog

To create a new catalog, complete the following procedure:

1. Choose the File menu from the main menu bar.

2. Choose New Catalog.

   A "Create new catalog" dialog box is displayed, as shown here.

   

3. Enter the full pathname in the Message Catalog field, or click the Browse button and navigate to the WebLogic catalog directory, $SRC/weblogic/msgcat.

4. Enter the name of the new catalog, which must include the xml extension.

5. Use the dropdown list to indicate whether your catalog is to be a log message catalog or a simple text message catalog.

   If this is to be a log message catalog, the Base ID and End ID fields are displayed; if it is to be a simple text message catalog, those fields disappear.

6. Enter the remainder of the fields, and click Create Catalog.

   The dialog box disappears, and the catalog you just created is displayed as the context catalog in the main Message Editor window.

Entering a New Log Message

The entire catalog is written to disk immediately upon adding the message.

To enter a new message into a log catalog, complete the following procedure:

1. Enter a message ID, or click the Get next ID button to get the next numerical ID which is unique in the context catalog.

2. Enter the appropriate method, including parentheses and any arguments. For example:

   logNoAuthorization(String arg0, java.util.Date arg1, 
      int arg2) logNote()

3. Choose a severity from the list of possible levels.

4. Enter the message body, detail, cause, and action. Parameters are denoted by {n}. For example:

   User {0} tried to access this on {1} but has no authority to do so. {2} lashes with a keyboard with coke spilled on it.

5. Click Add.

   The entire catalog is written to disk immediately after the message is added.

Entering a New Simple Text Message

The entire catalog is written to disk immediatly upon adding the message.

1. Enter an alphanumeric ID for the message.

   This number must be unique within the catalog.

2. Enter the message body.

3. Click Add.

   The entire catalog is written to disk immediately after the message is added.

Finding a Log Message

1. Make sure that the context catalog is a log catalog.

2. Choose Edit from the main menu bar.

3. Choose Search to display the search dialog box.

   

4. Enter as much information as you need to search for and click Find first or Find next.

   The fields are strung together to find the message. The message ID and the method name must be complete, but the search for text does a partial match in any of the text fields.

If a matching message is found, it is displayed in the main Message Editor window, ready for editing.

Finding a Simple Text Message

Make sure that the context catalog is a simple text message catalog.

1. Choose Edit from the main menu bar.

2. Choose Search to display the search dialog box.

   

3. Enter as much information as you need to search for and click Find first or Find next.

The fields are strung together to find the message. The message ID must be complete, but the search for text does a partial match.

If a matching message is found, it is displayed in the main Message Editor window, ready for editing.

Viewing All Messages in a Catalog

To view all the message in a catalog, choose View from the main menu bar.

All the messages for the current catalog context are displayed in a table in the Message Viewer window, as shown.

Choosing a Message to Edit from the Catalog List

If you click on any row of displayed messaged in the Message Viewer, the designated row is selected, and the corresponding message appears in the main Message Editor window, ready for editing.

Viewing All Messages in Several Catalogs

If you view the messages from the current catalog context, and then change the context by browsing to a new catalog, the old view of the old catalog remains on the screen while you view the new catalog. Repeating this step allows you to view, at the same time, as many catalogs as you require (or can reasonably fit on your screen).

Choosing a Message to Edit from Any Catalog Shown

When you click on any row in any view the catalog context switches to the viewed catalog, and the message in that catalog is displayed in the Message Editor main window.

Editing an Existing Message

The entire catalog is written to disk immediately upon adding the message.

1. Find the message you want to edit, either by using the Search dialog box, or by clicking on a row in the message viewer.

2. Edit the fields you wish to change in the main Message Editor window.

3. Click Update.

   The entire catalog is written to disk immediately after the message is added.

Using the Internationalization Utilities

WebLogic Server provides three internationalization utilities:

• i18ngen-Message catalog parser

• l10ngen-Locale-specific message catalog parser

• CatInfo-Utility that lists installed log messages

i18ngen

The i18ngen utility parses message catalogs (XML files) to produce classes used for localizing the text in log messages. Used to compile the top-level message catalogs into Java classes and properties files.

Syntax

i18ngen [options] files

Options

Option	Definition
-d targetdirectory	Send generated Java files to this target. User catalog properties are placed in i18n_user.properties, relative to the target directory named in the -d designation.
-n	Parse and validate, but do not generate classes
-keepgenerated	Keep generated Java source
-ignore	Ignore errors
-i18n	Generate internationalizers (for example, Loggers)
-l10n	Generate Localizers (for example, LogLocalizers)
-compile	Compile generated source
-nobuild	Parse and validate only
files	Process the files and directories in this list of files.

The i18ngen utility creates or updates the i18n_user.properties file.

The option i18ngen -i18n creates the internationalizer source (for example, *Logger.java) that supports the logging of internationalized messages.

The option i18ngen -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.

Errors detected during compilation generally result in no class files or properties file being created. i18ngen exits with a bad exit status.

The target directory (-d option) specifies the root directory in which generated source files are generated. Files are placed in appropriate directories based on the i18n_package and l10n_package values in the corresponding message catalog. The default target dir is the current directory.

The -compile option compiles generated Java files using the current CLASSPATH. The resulting classes are placed in the directory identified by the -d option.

The i18ngen utility processes all files listed on the command line. 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. Any errors, warnings, or informational messages are sent to stderr.

l10ngen

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

Syntax

java weblogic.i18n.tools.l10ngen [options] filelist

Options

CatInfo

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.i18n.tools.CatInfo [options]

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.