Extending the Administration Console

Using Localization in a Console Extension

The following sections describe how to localize the text in your Administration Console Extension:

Overview of Console Extension Localization

Localizing your Administration Console extension allows you to present your console extension in a variety of languages. You store the localized text in special localization catalog files, one for each language you want to present. You also describe all of the catalog files in a file called index.xml. You package the index.xml file and the catalog files in the Web Application that defines your console extension, as described in Packaging the Administration Console Extension.

You can localize the following parts of your console extension:

Labels for nodes in the navigation tree
Labels for right-click menu options in the navigation tree
Labels for tabs in the console screens
Any text you want to display in the console screens.

How the Console Determines Which Localization Catalog to Use

To determine which localization catalog to use to display the console, the console application uses a combination of the language preference set in the Administration Console, the language and country specified in the user's Web browser, and settings in the index.xml file. The index.xml file (see Writing the index.xml File) lists all the available localization catalogs and associates them with a language preference, and one or more locale settings. Locale settings include Country and Language attributes.

The console application checks the language preference set in the Console --> Preferences screen in the Administration Console. If a language is specified, the console looks at the name attribute of the <catalog> element in index.xml file to find the localization catalog associated with the language.

Note: If no language has explicitly been set in the Console --> Preferences screen, English will show as the default in the Language field.) If no preference is set, the console application looks at the <locale> elements in the index.xml file to find a Country and Language that matches the values set in the user's Web browser.

Main Steps for Console Extension Localization

To use localized text in your console extension:

Create an XML catalog file for each language you want to present. These XML files contain an ID string that you use to reference the localized text. This ID string is the same in each language catalog. The ID string points to a block of text that is retrieved from the catalog and displayed in the console.

For detailed instructions, see Writing a Localization Catalog

Create an index.xml file that lists all of your localization catalogs.

For detailed instructions, see Writing the index.xml File.

Display localized text using JSP tags in the Console Extension Tag Library. Each JSP tag has an attribute you use to specify the catalog ID. For more information, see Using localized text in JSPs.

Package your JSPs, catalogs, and Java classes as a Web Application. See Packaging the Administration Console Extension.

Deploy the Web Application containing your console extension on the Administration Server in your WebLogic Server domain. See Deploying an Administration Console Extension

Writing a Localization Catalog

You write localization catalogs using XML notation. You can use an XML editor or any plain-text editor. For a sample catalog, see Sample Localization Catalog.

To write a localization catalog:

Create the localization catalog as a plain text file and save it in the WEB-INF/catalogs directory of the Web Application containing your console extension. The file name of the catalog must match the file attribute of the <catalog> element in index.xml (see Writing the index.xml File) that defines this localization catalog.

The catalog file must contain the following base XML elements: <?xml version="1.0" ?> <catalog> (Insert your catalog data here.) </catalog>

Create the localized text entries.

To localize single words or short phrases, see Localizing Single Words or Phrases.
To localize longer blocks of text, see Localizing Long Blocks of Text.

Create an entry for the catalog in the index.xml file in the WEB-INF/catalogs directory. For instructions, see Writing the index.xml File.

Localizing Single Words or Phrases

To create localized text for single words or phrases:

Use the <textlist> element. Within a <textlist> element you can create multiple entries of localized text as name/value pairs in the form:

textid = localized text string

Wrap all of the localized text entries in a <textlist> element with the following XML:

<![CDATA[
...
]]>

For example:.

<textlist>
<![CDATA[

example.mytext      = This is localized text from the catalog.
example.title       = Console Extensibility Example
example.tab.extra   = Extra
example.tab.1       = Extension Catalog Text
example.tab.2       = Console Catalog Text
example.tab.3       = Programmatic
]]>
</textlist>

Localizing Long Blocks of Text

To create localized text for long text strings:

Use the <text> element, specifying the localization catalog ID using the id attribute. For example:

<text id='example.error-message'>

Insert the localized text between the <text> and </text> tags. You may use HTML tags within this text.

Wrap the localized text with the following XML:

<![CDATA[
...
]]>

For example:

<text id='example.error-message'>
<![CDATA[
An <b>error</b> has occured.
<p> Please consult the documentation for more information. 
]]>
</text>

Writing the index.xml File

The index.xml file maps a language to a catalog file and provides other details about the display of the localized text.

To create the index.xml file:

Create the index.xml file as a plain-text file in the WEB-INF/classes directory of the Web Application containing your console extension.

The catalog file must contain the following base XML elements: <?xml version="1.0" ?> <index> (Insert your catalog definitions here.) </index>

Create a <catalog> element for each catalog that you define. Within this element, define the following attributes:

Attribute	Description
`name`	The name of the Language. For more information, see How the Console Determines Which Localization Catalog to Use
`file`	The path and filename of the catalog file to use for this language. Specify the path relative to the `index.xml` file. (The `index.xml` file should be located in the `WEB-INF/catalogs` directory of the Web Application containing your console extension.
`charset`	The name of the character set to use to display the localized text. Use a standard character set name as defined by the World Wide Web Consortium (W3C).
`encoding`	The name of the encoding to use when displaying the localized text. Use a standard encoding as defined by the World Wide Web Consortium (W3C).

Create one or more <locale> sub-elements within the <catalog> element. The Administration Console application matches the settings in the user's Web browser with these attributes to determine which catalog to use. (For more information, see How the Console Determines Which Localization Catalog to Use.)

Attribute	Description
`country`	Country as specified at http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt.
`language`	Language as specified at http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

Create additional <catalog> and <locale> elements for each language catalog in your console extension.

Sample Localization Catalog

Listing 3-1 english.xml

<?xml version="1.0" ?>


<catalog>

<text id='example.error-message'>
<![CDATA[
An <b>error</b> {0} has occured.
<p> Please consult the documentation for more information. 
]]>
</text>


<textlist>
<![CDATA[

example.mytext	      = This is localized text from the catalog.
example.title         = Console Extensibility Example
example.copyright     = Copyright 2001 BEA Systems.
example.dialog        = This is an example dialog for the server named {0}.
example.tab.extra     = Extra
example.tab.1         = Extension Catalog Text
example.tab.2         = Console Catalog Text
example.tab.3         = Programmatic
example.tab.4         = Switch on the Fly
]]>
</textlist>
</catalog>

Using localized text in JSPs

The following sections discuss the JSP code you use to localize various elements of your console extension.

Localizing the Navigation Tree Nodes

To create a localized node in the navigation tree, use the labelId attribute of the <wl:node> tag. For more information, see <wl:node> Tag.

For example. the following code creates a node whose label is looked up in the localization catalog under the ID node1:

<wl:node 
   labelId='node1' 
   icon='/images/bullet.gif'
   url='/dialog_domain_example.jsp'>
</wl:node>

Localizing Right-Click Menus

To create a localized right-click menu, use the labelId attribute of the <wl:menu> tag. For more information, see <wl:menu> and <wl:menu-separator> Tags.

For example. the following code creates a node with a right-click menu. The labels for the menu items are looked up in the localization catalog using the ID beaDocs and beaHome:

<wl:node 
   label='My 2st nested node'
   icon='/images/bullet.gif'>
   <wl:menu 
      labelId='beaDocs' 
      url='http://www.oracle.com/technology/documentation/index.html' 
      target='_blank'/>
   <wl:menu-separator/>

    <wl:menu 
        labelId='beaHome' 
        url='http://www.bea.com' 
         target='_blank'/>

</wl:node>

Localizing Tab Labels

To create a localized label for a tabbed dialog, use the labelId attribute of the <wl:tab> tag. For more information, see <wl:tab> Tag.

For example, the following code uses a localized label for a tab. The label is looked up in the localization catalog using the ID tab.1:

<wl:tab name='LocalizedTextTab' labelId='tab.1'>
      The tab label for this tab comes from the catalog. 
</wl:tab>

If you do not specify the labelId attribute, the console looks for an entry in the localization catalog with the form

tab + name

Localizing Text in Console Dialogs

To create localized text in your console screen, use the textId and the textParamId attributes of the <wl:text> tag as described in the next two sections. For details on this tag, see <wl:text> Tag.

Localizing Text

To localize text, use the textId attribute of the <wl:text> tag to look up text in the localization catalog. For example, the following code looks up the ID LocalizedText.1 in the localization catalog:

<wl:tab name='LocalizedTextTab' labelId='tab.2'>
    <wl:text textId='LocalizedText.1'/>
</wl:tab>

Localizing Parameters

You can also localize parameters. Parameters are substituted for the string {0}, when the string is stored in the localization catalog.

For example, in the following code, the localized text stored in the catalog under the ID LocalizedParam.1 will be appear in place of the string {0}, which is stored under the ID LocalizedText.3.

<wl:text 
  textId='LocalizedText.3'
  textParamId='LocalizedParam.1' />

Specifying the Character Set for the Response

To specify the character set the browser uses to code the response, insert the following code in all your console extension JSPs, after any JSP Directives (JSP Directives begin with <%@).

<%@ page import='weblogic.management.console.catalog.Catalog' %>
<%@ page import='weblogic.management.console.helpers.Helpers' %>
<%
Catalog catalog = Helpers.catalog(pageContext);
String charset = catalog.getCharset();
if (charset != null)
response.setContentType("text/html; charset="+charset);
%>