Chapter 9   Localizing Sun ONE Portal Server

This chapter provides instructions for localizing the customizable parts of Sun^TM ONE Portal Server software:

• Templates and JSPs
• Resource Bundles
• Display Profile Properties
• Localization Support in PAPI

Templates and JSPs

This section addresses the Desktop templates and JavaServer Pages^TM (JSP^TM) in the Sun ONE Portal Server software that can be translated to support localization.

Desktop Templates

HTML Templates

The /etc/opt/SUNWps/desktop/ directory contains templates that are used to generate the Desktop pages. For each directory contained in this directory, a new directory for the locale must be created. The directory name must contain the existing directory with an underscore and the name of the locale; for example, /etc/opt/SUNWps/desktop/default is translated to /etc/opt/SUNWps/desktop/default_locale.

All of the filenames can remain the same. Only files that require translation must be created in the locale-specific directory. If a file is not found in the locale-specific directory, it is automatically taken from the directory that does not have the locale specifier.

Template files are mostly markup text with embedded tags that specify substitutions to be performed at runtime. The tags have the form [...]. The tags should not be modified during the translation process.

Each template file is encoded using Java Unicode encoding where non-ASCII characters are represented with \uXXXX notation. Here the \uXXXX is the hexidecimal representation of the Unicode value for the character. This type of file can be created from a native file using the Java native2ascii program available in the Java^TM Development Kit (JDK) 1.3.1 package that is shipped with the Sun ONE Portal Server.

JSPs

JSP files end with the .jsp suffix. The encoding for each top-level JSP file is specified using a header at the top of the file. The header must look like the following:

<%@ page contentType="text/html; charset=encoding" %>

where encoding is the desired encoding such as UTF-8 or EUC-JP. Note that this is only for top-level JSP files. JSPs that are statically included by other JSPs must use the encoding of the including JSP. That is, JSPs that are statically included by other JSPs using

<%@ include file="relativeURL" %>

must use the encoding of the including JSP. JSPs that are dynamically included using:

<jsp:include page="{ relativeURL | <%= expression %>}" flush="true" />

must have their own page directive that contains the encoding.

Images

If image files referenced by the existing templates are inappropriate for a locale, the references can be changed to refer to new files. The new file must be placed in the document root of the web container at BaseDir/SUNWam/public_html directory or you can deploy a new WAR file into the location of your choice.

File Lookup Mechanism

Desktop content can be customized based on the following factors:

• Desktop type
• Locale
• Client type

The DesktopServlet performs a search for a localized file before selecting a default. In order to perform the search, the DesktopServlet uses the user's locale attribute in the user's directory entry (or preferredLocale attribute in the iPlanet^TM Directory Server Access Management Edition software) and searches using the following algorithm:

The directory search order of the template file, defined in ProfileProviderAdapter.getTemplate method, is as follows:

type_locale/component/clientPath

type_locale/provider/clientPath

type_locale/component

type_locale/provider

type_locale/clientPath

type_locale

type/component/clientPath

type/provider/clientPath

type/component

type/provider

type

default_locale/component/clientPath

default_locale/provider/clientPath

default_locale/component

default_locale/provider

default_locale

default/component/clientPath

default/provider/clientPath

default/component

default/provider

default/clientPath

default

Where

• type is the value of the desktop template type property
• locale is the user's locale
• component is the component name (or channel name)
• provider is the provider name
• clientPath is an optional file-path containing client-specific templates

If there is no clientPath specified, then the directory search order is as follows:

type_locale/component

type_locale/provider

type_locale

type/component

type/provider

type

default_locale/component

default_locale/provider

default_locale

default/component

default/provider

default

Locales are searched from more to less specific. For example, for a locale setting of en_US_WE, the search order would be: en_US_WE, en_US, en. If the locale-specific property is not found, then the non-locale-specific version is returned (if it exists).

Resource Bundles

Resource bundles contain locale-specific objects. When your program needs a locale-specific resource, a String for example, your program can load it from the resource bundle that is appropriate for the current user's locale. See the documentation on Resource Bundles at http://java.sun.com/products/jdk/1.2/docs/api/java/util/ResourceBundle.html for more information on:

• The structure of the Resource Bundle
• The search look-up mechanism of Resource Bundles

The Desktop and the Desktop Providers use Java Resource Bundles for the localized on screen text.

Resource bundle for providers store content that is not included in display templates (such as error messages and dynamic content). The Sun ONE Portal Server automatically loads the correct resource bundle for the user's locale (see Resource Bundle Access for more details).

File Naming Convention

The file name for the resource bundle is usually the provider name, that is, the name defined in the display profile when the provider class is declared. For example:

<Provider name="Bookmark" class="com.iplanet.portalserver.providers.bookmark.BookmarkProvider ">

Here, for the BookmarkProvider, the resource bundle file name is Bookmark.properties. The provider name will be retrieved via the ProviderContext.getProviderName method.

The provider can also use a different name (different from the default name) for the resource bundle. The name must be passed as a key when calling ProviderAdapter.getResourceBundle(String key) method.

File Installation Location

The resource bundle files must be installed in the /etc/opt/SUNWps/desktop/classes directory. For each X.properties file, create a X_locale.properties file that contains the translation. The translated file must be installed into the same directory as the English version.

File Entries Format

Each line of the properties file uses the format key=value. Lines can be continued using a backslash (\) at the end of the line. The .properties files are encoded using Java Unicode encoding where non-ASCII characters are represented using \uXXXX notation. Here, the \uXXXX is the hexidecimal representation of the Unicode value for the character. This type of file can be created from a native file using the Java native2ascii program available in the JDK 1.3.1 package that is shipped with Sun ONE Portal Server.

The messages represented by the value part of the line are formatted using the conventions of the Java java.text.Message format class. See the Javadocs for this class for more details on how to express parameters within messages. Parameters are enclosed in curly braces ({}).

Resource Bundle Access

The ProviderAdapter.getResourceBundle() method loads the correct resource bundle for the user's locale and if the specified locale is not found, it loads the default resource bundle. That is, it will look for the providerName_locale.properties file; if it is unable to find the specified properties file, it will look for providerName.properties file and load it.

Display Profile Properties

The display profile can be modified by using XML files that are input to the dpadmin command. The encoding for display profile XML file is specified using the following XML header at the top of the file:

<?xml version="1.0" encoding="encoding"?>

where encoding is whatever encoding is suitable for the content of the file. Typically, the encoding is UTF-8; but it can also be other native encodings such as SJIS or ISO-8859-1. The DesktopServlet always converts characters internally to Unicode and stores them in the directory using UTF-8.

Every XML fragment must include a xml header and a doctype declaration as shown below:

<?xml version="1.0" encoding="encoding" standalone="no"?>

<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">

The display profile contains text strings for items such as channel titles and descriptions. These strings can be localized.

For example, the user information channel is defined by the following element in the display profile:

<Channel name="UserInfo" provider="userinfo" merge="fuse" lock="false">

<Properties merge="fuse" lock="false" name="_properties">

<String name="title" value="User Information" merge="replace" lock="false"/>

<String name="description" value="View/Edit User Information" merge="replace" lock="false"/>

</Properties>

</Channel>

`

1. To localize the user information channel (title and description), the <Locale> tag must be added. For example, the following modifications must be included (modifications are shown in bold):

<Channel name="UserInfo" provider="userinfo" merge="fuse">

<Properties merge="fuse" name="_properties">

<String name="title" value="User Information" merge="replace"/>

<String name="description" value="View/Edit User Information" merge="replace"/>

<Locale language="fr" country="FR">

<String name="title" value="User Information in French"/>

<String name="description" value="View/Edit Use Information in French"/>

</Locale>

</Properties>

</Channel>

The <Locale> element can be used to group localized properties and it can hold any other property element.

2. To add this, the following sample display profile fragment (stored in file dp-locale.xml) is needed:

<?xml version="1.0" encoding="utf-8" standalone="no"?>

<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">

<Locale language="fr" country="FR">

<String name="title" value="User Information in French"/>

<String name="description" value="View/Edit Use Information in French"/>

</Locale>

3. To upload the XML display profile fragment using dpadmin (using the add subcommand with the parent option), type:

      BaseDir/SUNWps/bin/dpadmin add -p parent -u dn_amadmin -w password -d distinguishedname dp-locale.xml

Localization Support in PAPI

The ProviderContext contains localization-aware methods such as:

• getCollectionProperty(java.lang.String Channel,java.lang.String name, boolean localized) and getCollectionProperty(java.lang.String channel, java.lang.String name, java.util.Map def, boolean localized) which gets the localized version of a collection property
• getStringProperty(java.lang.String channel, java.lang.String name, boolean localized) and getStringProperty(java.lang.String Channel,java.lang.String name, java.lang.String def, boolean localized) which gets the localized version of a String property

The ProfileProviderAdapter contains localization-aware methods such as:

• getMapProperty(java.lang.String key, boolean localized) and getMapProperty(java.lang.String key, java.lang.String def, boolean localized) which gets the localized version of a map property for the channel
• getStringProperty(java.lang.String key, boolean localized) and getStringProperty(java.lang.String key, java.lang.String def, boolean localized) which gets a localized string property for the channel

If localized is true, then this method will attempt to find a localized version of the map/string named by the key. The locale for the user who this object is executing is read from the ProviderContext object associated with this provider object.

See the Javadocs for more information on these methods.