1. Developing Applications for Event Processing with Oracle Stream Analytics
  2. Internationalization

12 Internationalization

You can use message catalogs to internationalize message text that your application sends to the server log or displays to the user. The messages can provide information about anything occurring in the application, such as which user invoked specific application components, error conditions, or help you debug an application before its release.

This chapter includes the following sections:

12.1 Message Catalogs

A message catalog is a single XML file that contains a collection of messages, with each message indexed by a unique ID. All internationalized text is externalized and defined in message catalogs and each message catalog defines a collection of log messages or simple text.

With message catalogs, message strings can be converted to multiple locales without changing or recompiling the application code.

Message IDs are unique across all log message or locale message catalogs. Within the message catalog file, each localized version of the message is assigned a unique message ID and message text specific to the error. Ideally, a message is logged from only one location within the system so that a support team can easily find it. Message IDs in simple text catalogs are unique within each simple text catalog.

There are the following three types of message catalogs:

  • Log message catalogs: Informational or error messages that your application logs to the server logs.

  • Simple text message catalogs: Simple messages that your application displays to the user.

  • Locale message catalogs: A collection of locale-specific messages that correspond to a top-level log message catalog or a simple text catalog that contains the English version of the messages. There are corresponding locale-specific catalogs with one catalog for each additional supported locale.

    The top-level English version catalog has all of the information needed 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.

You create your own catalog of log or simple text messages and use Oracle WebLogic utilities to generate Java classes that have logging methods. You import the Java classes into your application code, and implement your application code to supply runtime values to the logging methods. The log messages generated by the logging methods are integrated with and treated in the same way as log messages that are generated by the Oracle Stream Analytics server.

The message catalog files are defined by one of the following XML document type definition (DTD) files:

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

  • l10n_msgcat.dtd: Describes the syntax of locale-specific catalogs.

The DTDs are stored in /Oracle/Middleware/wlevserver/modules/ com.bea.core.i18n.generator_VERSION.jar. VERSION points to a particular version that changes.

You can create a single log message catalog for all logging requirements, or create smaller catalogs based on a subsystem or on Java packages. Oracle recommends using multiple subsystem catalogs so you can focus on specific portions of the log during viewing. For simple text catalogs, Oracle recommends that you create a single catalog for each utility to be internationalized

12.1.1 Hierarchy

All messages must be defined in the default, top-level catalog. 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 called ..de/mycat.xml. Typically the top-level catalog is English. However, English is not required for any 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 example, en\US, indicates American English. The name of the associated catalog is ..en\US\mycat.xml. Variants are specific to a vendor or browser and are used to introduce minor differences, such as collation sequences, between two or more locales defined by either language or country.

12.1.2 Naming

Because the name of a message catalog file, without the .xml extension, is used to generate runtime class and property names, choose the name carefully. Follow these guidelines for naming message catalogs:

  • Do not choose a message catalog name that conflicts with the names of existing classes in the target package for which you are creating the message catalog.

  • Choose message catalogs names that contain only 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:

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

  • Simple text catalogs message IDS can consist of any string value.

  • Java lets you group classes into a collection called a package. Oracle recommends that a package name be consistent with the name of the subsystem in which a particular catalog resides. Consistent naming makes OSGi imports easier to define.

  • The log Localizer classes are actually ResourceBundle property files.

12.1.3 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. Make sure your message content conforms to the patterns defined by java.text.MessageFormat.

Arguments are values that can be dynamically set at runtime. These values are passed to routines, such as a routine for printing 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 (message body, message detail, probable cause), although the message body must include all of the arguments.

  • Only the message body section in a simple text message can include arguments.

  • You must assign a severity level for log messages. Log messages are generated through the generated Logger methods, as defined by the method attribute.

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.

  • Arguments are type String or representable as a String type.

  • Numeric data is represented as {n,number}.

  • Dates are supported as {n,date}.

The following excerpt from an XML log message definition shows how to 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. In the following example, {0} represents the file that cannot be opened, while {1} represents the file that is opened in its place. 

<messagebody>Unable to open file, {0}. Opening {1}. All arguments must be in body.</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 is as follows:

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

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

  • Both are used in the <messagebody>

  • Both are used in the <messagedetail>

  • Neither is used in <cause> or <action>

12.1.4 Formats

The catalog format for top-level and locale-specific catalog files differs. 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. Also, log message catalogs are defined differently from simple text catalogs.

Log Message Catalog

This example shows the MyUtilLog.xml message catalog that has one log message to show how to use the messagebody, messagedetail, cause, and action elements. 

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/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
    </cause>
     the security log.
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </log_message>
</message_catalog>

Simple Text Catalog

This example shows the MyUtilLabels.xml text catalog with one text definition. 

<?xml version="1.0"?> 
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
    "http://www.bea.com/servers/wls90/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>

Locale-Specific Catalog

This example shows a French translation of a message that is in the ..\msgcat\fr\MyUtilLabels.xml file. 

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC 
   "weblogic-locale-message-catalog-dtd"
   "http://www.bea.com/servers/wls90/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 you enter text in the messagebody, messagedetail, cause, and action elements, 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.

12.1.5 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.

You can achieve variations to language codes with 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 helpful when there is a functional difference in platform vendor handling of specific locales. Examples of vendor variants are WIN, MAC, and POSIX. There may be two variants used to further qualify the locale. In this case, the variants are separated with an underscore (for example, Traditional_Mac as opposed to 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 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.

12.2 Generate Localization Classes

After you create your message catalog XML files, use the weblogic.i18ngen utility to create the Logger and TextFormatter classes that localize the text in log messages. The weblogic.i18ngen utility creates or updates the i18n_user.properties properties file that loads the message ID lookup hashtable weblogic.i18n.L10nLookup.

Any errors, warnings, or informational messages are sent to stderr.

For user catalogs to be recognized, the i18n_user.properties file must reside in a directory identified in the Oracle Stream Analytics server class path. Oracle recommends that the i18n_user.properties file reside in the Oracle Stream Analytics server class path. If the i18n_user.properties file is in targetdirectory, then targetdirectory should be in the Oracle Stream Analytics server class path.

Parse a Message Catalog to Generate the Logger and TextFormatter Classes

The following steps summarize how to create an internationalized message to use with the Oracle Stream Analytics server.

  1. Create or edit a top-level log message catalog or simple text message catalog by defining the messages in the catalog.

    In addition to message text, include information about the type and placement of runtime values that the message contains.

  2. Run weblogic.i18ngen to validate the catalog you created or edited in Step 1 to generate the Logger and TextFormatter classes. 

    java weblogic.i18ngen [options] [filelist]

    The generated classes contain a method for each message. The class is defined according to information specified in the message catalog entry. The classes include methods for logging or getting message text, depending on the type of catalog. The class name ends with Logger or TextFormatter. For details, see weblogic.i18ngen Utility.

    Table 12-1 weblogic.i18ngen Utility Options

    Option Description

    -build

    Generates all necessary files and compiles them. Combines the -i18n, -l10n, -keepgenerated, and -compile options.

    -d targetdirectory

    Specifies the root directory for the generated Java source files. User catalog properties are placed in i18n_user.properties, relative to the targetdirectory. 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 and 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).

    -l10n

    Generates localizers (for example, LogLocalizers and TextLocalizers).

    -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 time stamps in the catalog. If the catalog is writable and time stamps have been updated, the catalog is rewritten.

    filelist

    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.

  3. Create locale-specific catalogs as needed for the message catalog you created in Step 1.

  4. Run weblogic.l10ngen to process the locale-specific catalogs you created in Step 3.

  5. Code your application to use the Logger or TextFormatter classes you generated in Step 2.

    Use the OSGi import statements in the application MANIFEST.MF file to import the following packages into your Oracle Stream Analytics application:

    weblogic.i18n.logging weblogic.logging

    When your application calls one of the Logger or TextFormatter methods to log or return a message, the method writes the localized version of the message text to the target location. A Logger method writes the localized version of the message to the localized log files, and a TextFormatter method writes the localized version of the message to the display.

  6. Make sure that the i18n_user.properties file is in the Oracle Stream Analytics server class path.

    The weblogic.i18ngen utility generates the i18n_user.properties file that loads the message ID lookup hashtable weblogic.i18n.L10nLookup.