Creating Multilingual Portals

Print-friendly Version

The Sun Java Enterprise System installer supports seven languages—Spanish, German, French, Japanese, Korean, Simplified Chinese, and Traditional Chinese. Sun Java System Portal Server 7 (henceforth, Portal Server), part of Sun Java Enterprise System, automatically detects the user locale from the http header.

You can customize Portal Server to display relevant content, such as time, currency, date, number formats, units, and messages, for any or all of those locales. In particular, you can explicitly set the user locale in the User Information Channel on the Portal Server desktop by choosing the language from a drop-down menu. This article tells you how to enable multilingual support.

Your language isn't on the list? This article also explains how to add support for new languages in Portal Server.

We assume that you are familiar with Portal Server concepts, such as providers, containers, and channels.

Note: Creating multilingual portlets—Java technology-based Web components managed by portlet containers—involves a separate process. A future article will address that topic.

For reference, the following table shows the default installation, data, and configuration directories of Portal Server in the Solaris Operating System and Linux.

Operating System	Default Installation Directory	Default Data Directory	Default Configuration Directory
Solaris on SPARC and x86 architectures	/opt	/var/opt/SUNWportal	/etc/opt/SUNWportal
Linux	/opt/sun	/var/opt/sun/portal	/etc/opt/sun/portal

Multilingual support in software involves two processes:

• Internationalization (I18N) — The engineering practice that ensures that software can run in various locales according to the user's locale choice without engineering changes
  
  
• Localization (L10N) — The process of translating software messages, UI wording, and specific standard conventions into the desired language and integrating all of them with the software

You can configure support for all seven languages supported by Sun Java Enterprise System while installing Portal Server: Select "Install Multilingual package(s) for all selected components" in the Component Selection pane. Otherwise, unconfigure Portal Server, add the localized packages, and then configure Portal Server again.

Caution: Unconfiguring Portal Server deletes all your customizations.

For details, see Sun Java System Portal Server 7 Installation Guide.

To add the localization packages, manually add the Portal Server L10N packagese from the Java Enterprise System installer CD.

To add support for all seven languages:

1. Type:
   # cd Portal-Server-install-dir/Product/portal_svr/Packages
   
   where Portal-Server-install-dir is the location for the product bits on the Java Enterprise System installer CD.
   
   
2. Type:
   # pkgadd -d . package-name-l10n
   
   For example, for the Portal Server base L10N package, type:
   # pkgadd -d . SUNWportal-base-l10n

This section explains how to add to Portal Server a language that is not supported by Java Enterprise System. The process consists of four major steps and one optional step:

1. Localize the display profile (DP), an XML file.
   
   
2. Optional. Add locale information to the DP.
   
   
3. Add the supported charset for the new locale in Sun Java System Access Manager (henceforth, Access Manager).
   
   
4. Localize the Container and Provider property files.
   
   
5. Localize the channel JavaServer Pages (JSP) pages and templates.

The example in the following subsections shows how to add support for the Russian language (ru).

A Portal Server DP performs two tasks:

• Declares and customizes providers and channels.
• Defines the attributes that you must customize to localize a given channel.

You can localize the Provider and Channel properties either by using the Portal Server Admin Console (henceforth, Admin Console) or by downloading and editing the DP. Afterwards, upload the DP.

To localize the DP from the Admin Console:

1. Log in to the Admin Console at http://hostname.domain-name/psconsole.
   
   
2. Click the Portals tab and select the deployed portal, for example, portal1, and then the required distinguished name (DN) from the Select DN drop-down list, for example, DeveloperSample[Org].
   
   
3. Click Manage Containers and Channels.
   
   
4. From the left pane, select the Channel in which you would like to add localized values. For example, select userInfo under MyFrontPageTabPanelContainer.
   
   The channel properties are displayed on the right pane.
   
   
5. Click the Table Preferences button (the rightmost button at the top the Properties table).
   
   The Table Preferences dialog box is displayed.
   
   
6. Type the new locale name, ru, in the Locale field. Click OK.
   
   
7. Type the Russian translation of the content in the relevant fields.
   
   
8. Click Save.

Portal Server localizes DPs as a form of customization with the ConditionalProperties tag, which contains a locale-based attribute as the condition. The information that is displayed on the portal desktop from the DP includes the channel's title, help URL, tab names, and so on.

You can localize the DP properties by defining them within the ConditionalProperties block whose locale is en (for English). For another locale, localize and define its properties within its ConditionProperties block.

Example
The following code segment in a DP defines a channel named User Information.

<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="en" >
	    <String name="title" value="User Information"/>
	    <String name="description" value="View/Edit User Information"/>
	</ConditionalProperties>
    </Properties>
</Channel>

To localize the User Information Channel (title and description), add the ConditionalProperties tag for the locale, as follows. The edits are 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="en" >
	    <String name="title" value="User Information"/>
	    <String name="description" value="View/Edit User Information"/>
	</ConditionalProperties>

	<ConditionalProperties condition="locale" value="ru" >
	    <String name="title" value="?????????? ? ????????????"/>
	    <String name="description" value="??????????/??????????????? ?????????? ? ????????????"/>
	</ConditionalProperties>
    </Properties>
</Channel>

Process

1. Download the DP.
   
   
   1. Log in to the Admin Console and click the Portals tab. Select the deployed portal, for example, portal1, and then the required DN, for example, DeveloperSample[Org].
      
      
   2. Click Download Display Profile.
      
      
   3. Type the file name in the Save File As dialog box.
      
      
   4. Click Save to save the file.
   
   
2. Edit the downloaded DP by adding the ConditionalProperties block with the localized content.
   
   Note: Keep a backup copy of the DP. The DP must be in UTF-8 encoding.

Next, upload the edited DP:

1. From the Admin Console, select the deployed portal, for example, portal1, and then the required DN, for example, DeveloperSample[Org].
   
   
2. Click Upload Display Profile.

Note: Uploading the DP from the Admin Console replaces the DP in LDAP with the uploaded DP.

When a portal supports a new locale, you can add the locale information to the DP. Afterwards, Portal Server updates the Language drop-down list accordingly. That way, to set their preferred locale, users can click the Edit button in the User Information Channel and then select the language from the drop-down list.

You can add the locale information by either using the Admin Console or editing the DP.

Note: You can skip this step if you plan to display the localized desktop in only the browser locale, not the user locale.

To add locale information to the DP from the Admin Console:

1. From the Admin Console, click the Portals tab, select the deployed portal, for example, portal1, and then the required DN, for example, DeveloperSample[Org].
   
   
2. Click Manage Containers and Channels.
   
   
3. Select DP XML Tree at the top of the View Type drop-down list.
   
   
4. Click the DP_Root link at the top of the left pane.
   
   
5. Click the property named locales in the right pane and then the New Property button at the top of the Properties table.
   
   The New Property wizard is displayed.
   
   
6. Select String under Type as the property type. Click Next.
   
   
7. Type ru in the Name text field as the locale name and Russian in the Value text field. Leave the default of False under Advanced as is. Click Finish.
   
   Portal Server confirms the result: "Property created successfully."
   
   
8. Click Close.
   
   
9. Click the Table Preferences button in the Properties table and type ru in the Locale field. Click OK.
   
   Portal Server displays the Properties window with the locales displayed.
   
   
10. For en under Name, type ??????????(???), which stands for English (United States) in Russian, in the Value text field. Similarly, type the Russian translation for all the other property names.
    
    
11. Click Save.

Alternatively, create a file, dp-locale_ru.xml, with the following content.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<DisplayProfile version="1.0" priority="0">
    <Properties>
	<Collection name="locales">
	    <String name="en_US" value="English (United States)"/>
	    <String name="ru" value="Russian (Russia)"/>
	</Collection>
	<!-- translate this -->
	<ConditionalProperties condition="locale" value="ru">
	    <Collection name="locales">
	        <String name="en_US" value="??????????(???)"/>
		<String name="ru" value="???????(??????)"/>
	    </Collection>
	</ConditionalProperties>
    </Properties>
<Channels/>
<Providers>
</Providers>
</DisplayProfile>

If Portal Server also supports other locales, add their names under Collection.

Next, upload the edited DP by typing this psadmin modify-dp command (all on one line):

# /opt/SUNWportal/bin/psadmin modify-dp -u amadmin -f /tmp/pass -m -d o=DeveloperSample,RootDN -p portal1 /tmp/dp-locale_ru.xml

where RootDN is the root DN.

By default, Portal Server displays the desktop in ISO-8859-1 encoding. To add a locale, you must specify the encoding for the desktop. Follow these steps:

1. Log in to the Access Manager Admin Console at http://hostname.domain-name/amserver/console.
   
   
2. Click the Configuration tab.
   
   
3. Click Globalization Settings under Console Properties.
   
   
4. Under Charsets Supported by Each Locale, click the Add button.
   
   
5. Type ru in the Locale text field and UTF-8 in the Supported Charsets text field. Click OK.
   
   
6. Click Save.

Portal Server now displays the desktop in UTF-8 encoding for the Russian locale.

Localize the container and provider property files under /opt/SUNWportal/websrc/WEB-INF/classes. Afterwards, redeploy the portal's Web applications to integrate the localized files into the portal Web archive (WAR) file (portal.war) and redeploy them to the Web container.

To redeploy the portal.war file, type, for example:

# /opt/SUNWportal/bin/psadmin redeploy -u amadmin -f /tmp/pass -p portal1

/tmp/pass refers to the administrator password file; portal1 is the default for portal-id. Replace them with the values that apply to your environment.

Portal Server generates the user interface in the rendered desktop with JSP pages or templates. The default JSP pages and templates are in the /var/opt/SUNWportal/portals/portal-id/desktop directory.

The resource bundles of the Portal Server JSP pages reside at /var/opt/SUNWportal/portals/portal-id/desktop/classes. To localize a JSP page for a new locale, copy the English property file to the locale-specific property file. For example, to add Russian support for the discussion JSP pages:

1. Copy DiscussionsJSP.properties to DiscussionsJSP_ru.properties.
   
   
2. Translate DiscussionsJSP_ru.properties.

Portal Server looks up the portal JSP pages and templates according to their desktop type, locale, client, channel name, and provider name.

The template's resource bundle, called message.properties, resides in the same directory as the template. For example, to localize the template /var/opt/sun/portal/portals/portal-id/desktop/default/UserInfo/html/edit.template:

1. Translate the English message.properties file under /var/opt/sun/portal/portals/portal-id/desktop/default/UserInfo/html into Russian.
   
   
2. Copy the translated file to /var/opt/sun/portal/portals/portal-id/desktop/default_ru/UserInfo/html/message.properties.

While creating or adding a JSP page or template, you can move the English messages to a property file with the I18N tag libraries and template tags in that page or template. That way, you need not localize the channel JSP pages and templates.

With the I18N tag library in Portal Server, you can externalize the hard-coded English messages in JSP pages into a resource bundle. That bundles resides at /var/opt/SUNWportal/portals/portal-id/desktop/classes.

Here is what to do:

• Load the resource bundles with the <i18n:setBundle> tag.
  
  
• Display the localized messages from the resource bundles with the <i18n:message> tag.
  
  
• Define the message arguments with the <i18n:param> tag for message-formatting by the MessageFormat class.

Move hard-coded English messages in the template files to the message.properties file with the template tag msg. For details, see the Appendix.

Note: If you use the I18N tag library in the JSP pages, as described in the preceding section, you have moved the localizable messages to the property files. You need to localize those files only. Skip this section.

For fine-grained control over the translated messages and page layout, you can localize the contents of the JSP pages or templates in Portal Server. That is, you can translate the channel-specific JSP pages and templates at /var/opt/SUNWportal/portals/portal-id/desktop/desktop-type, as follows:

1. Create a locale-specific directory under /var/opt/SUNWportal/portals/portal-id/desktop by adding _locale to desktop-type.
   
   
2. Place the translated files under the locale-specific directory according to the same directory structure.
   
   For example, for the default desktop type, if the English file is at /var/opt/SUNWportal/portals/portal-id/desktop/default/BookmarkProvider/html/display.template, the corresponding location of the localized file is—
   
   /var/opt/SUNWportal/portals/portal-id/desktop/default_ru/BookmarkProvider/html/display.template

Afterwards, Portal Server looks up the portal JSP pages and templates according to the desktop type, locale, client, channel name, and provider name.

If the user locale is set, Portal Server displays the desktop in that locale. Otherwise, Portal Server displays it according to the browser locale. If the browser locale is also not set, Portal Server displays the desktop according to the server locale.

Set the user locale from the Portal Server desktop, as follows:

1. Log in to the desktop as the user for whom the locale is to be set.
   
   
2. Click the Edit button in the User Information Channel.
   
   
3. Select the preferred language from the Languages drop-down list.

For details on how to add a locale to the Languages drop-down list, see "Adding Locale Information to the Language Drop-Down List."

Recall that you can move the English messages to a property file with the I18N tag libraries and template tags in JSP pages or templates, thus eliminating the cycles for localizing the channel JSP pages and templates.

Portal Server places the resource bundles in the JSP pages in the /var/opt/SUNWportal/portals/desktop/desktop-type/classes directory. This appendix shows you how to load and retrieve messages from the resource bundles with the I18N tag library in Portal Server.

The I18N tag library defines three tags:

• i18n:setBundle — Loads a resource bundle. You can store the reference to this bundle in a var attribute.
  
  The locale of the resource bundle is determined by the user's preferred locale, which Portal Server reads from the ProviderContext object associated with the provider object. Because of this dependency, define the i18n:setBundle tag within the dt:obtainChannel or the dt:obtainContainer tag. For example, define setBundle after the tag <dt:obtainContainercontainer="$JSPProvider">.
  
  
• i18n:message — Displays a localized message from the resource bundle. The key attribute of this tag identifies the message to be retrieved from that bundle.
  
  
• i18n:param — Defines the arguments according to which the MessageFormat class formats the message. To format the message retrieved from the bundle, specify this tag along with i18n:message.

Here is an example. Change this JSP code—

<html>
<body>
<dt:obtainContainer container="$JSPProvider">
...
Hello <%=name %>
</dt:obtainContainer>
</body>
</html>

—to the following:

<html>
<body>
<dt:obtainContainer container="$JSPProvider">
<i18n:setBundle baseName="i18nMessages" var="msg"/>
...
<i18n:message key="hello" bundle="msg" >
<i18n:param value="<%=name %>" />
</i18n:message>
</dt:obtainContainer>
</body>
</html>

Accordingly, the resource bundle i18NMessages.properties will have the entry hello=Hello {0}.

Portal Server supports a new template tag named msg. You can place this tag in templates to move hard-coded English messages to a property file, message.properties. This file resides in the same directory as the templates. For example, the messages in the template file /var/opt/SUNWportal/portals/portal-id/desktop/default/userinfo/html/edit.template reside in /var/opt/SUNWportal/portals/portal-id/desktop/default/userinfo/html/message.properties. The English messages of all the templates under a directory go into the message.properties file under that directory.

The localized message.properties file is /var/opt/SUNWportal/portals/myPortal/desktop/default_ru/userinfo/html/message.properties. Note that Portal Server does not follow the standard Java mechanism for localizing template files because template tags are not as sophisticated as JSP files in defining and using resource bundles.

The following new tag is included in the Desktop templates:

[msg:key:tag1: ...] Insert the localized message by reading from the resource bundle. The first argument after msg determines the key for retrieving the message. The arguments that follow format the message. Portal Server allows zero or more arguments after the key.

Here is an example. Change the template code—

Hello [tag:firstName] [tag:lastName]

—to the following:

[msg:greeting:firstName:lastName]

Accordingly, the message.properties file will have the entry greeting=Hello {0} {1}.

Multilingual support is a much-desired enhancement for portals. Even in a global economy, we generally prefer to work in a familiar environment. The procedures for customizing to local conventions, as described in this article, are intuitive and simple. Do localize your portals!

• Sun Java System Portal Server
  • Main page
  • Developer home
  • Software Forum
  
  
• Weblogs
  • The Portal Post
  • The Aquarium
  
  
• Developer services
  • Support
  • Training and certification