Sun logo      Previous      Contents      Index      Next     

Sun ONE Portal Server 6.2 Developer's Guide

Chapter 11
Localizing Sun ONE Portal Server

This chapter provides instructions for localizing the customizeable parts of Sun™ ONE Portal Server software. It contains the following sections:

Templates and JSPs

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

Desktop Templates

Template Files

The /etc/opt/SUNWps/desktop/desktoptype 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.

Note

The desktoptype refers to the Desktop type attribute which is now a comma separated list. The usage of this attribute is described in Chapter 1 of the Sun ONE Portal Server 6.2 Desktop Customization Guide.

All of the file names 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™ 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 portal-server-install-root/SUNWps/web-src directory and then deploy it with the portal-server-install-root/SUNWps/bin/deploy redeploy command. 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:

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 Sun™ ONE Identity Server) and searches for the file. For more information on the search order, see "Presentation Method".

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 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 software 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 installed in the JDK_DIR directory specified in /etc/opt/SUNWps/PSConfig.properties file.

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="UserInfoProvider">

    <Properties>

        <String name="refreshTime" value="60" advanced="true"/>

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

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

    </Properties>

</Channel>

To Localize the User Information Channel

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

    2. <Channel name="UserInfo" provider="UserInfoProvider">

        <Properties>

            <String name="refreshTime" value="60" advanced="true"/>

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

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

            <ConditionalProperties condition="locale" value="fr" >

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

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

            </ConditionalProperties>

        </Properties>

    </Channel>

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

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

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

        <ConditionalProperties condition="locale" value="fr" >

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

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

        </ConditionalProperties>

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

    4. portal-server-install-root/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:

The ProfileProviderAdapter contains localization-aware methods such as:

See the Javadocs for more information on these methods.



Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.