Sun ONE Portal Server 6.2 Developer's Guide |
Chapter 11
Localizing Sun ONE Portal ServerThis chapter provides instructions for localizing the customizeable parts of Sun ONE Portal Server software. It contains the following sections:
Templates and JSPsThis 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.
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 BundlesResource 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 PropertiesThe 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:
To Localize the User Information Channel
- 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):
<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>
- 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">
<ConditionalProperties condition="locale" value="fr" >
<String name="title" value="User Information in French"/>
<String name="description" value="View/Edit User Information in French"/>
</ConditionalProperties>
- To upload the XML display profile fragment using dpadmin (using the add subcommand with the parent option), type:
portal-server-install-root/SUNWps/bin/dpadmin add -p parent -u dn_amadmin -w password -d distinguishedname dp-locale.xml
Localization Support in PAPIThe 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
- getCollectionProperty(String channel, String name, List pflist), getCollectionProperty(String channel, String name, Map def, List pflist), getStringProperty(String channel, String name, List pflist), getStringProperty(String channel, String name, String def, List pflist) to support conditional properties
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
See the Javadocs for more information on these methods.