Configuring Portlets for Internationalization and Localization

Print-friendly Version

Portlets are Java technology-based Web components that are managed by portlet containers and aggregated in the context of a portal. Usually, when you access a portal, you invoke a number of portlets. Each portlet produces a markup fragment that is combined with the markup of other portlets, all within the portal itself. Sun Java System Portal Server 7.x supports Java Specification Request (JSR) 168-compliant portlets, which can interoperate by adhering to the standards defined in JSR 168.

Internationalization (I18N for short) is the process of developing software whose core design does not make assumptions based on a locale. Potentially, internationalization handles all targeted linguistic and cultural variations (such as text orientation, date-time format, currency, accented and double-byte characters, sorting, and so forth) within a single code base.

Localization (L10N for short) is the process of customizing software and documentation for a particular language. That process includes the translation of menus and messages into the native language, also changes in the user interface to accommodate different alphabets and cultural requirements.

Through a sample portlet, this article describes the procedures for internationalization, localization, and deployment of internationalized portlets on Portal Server. That is, you learn how to display portlet content in various languages and how to add new language support to existing portlets.

This article assumes that you are familiar with the basics of developing Web applications and portlets. In addition, you must have installed Portal Server and configured the Developer Sample there. Afterward, you can view the Portal Server welcome page at http://hostname:portnumber/portal/dt and access the Portal Server Administration Console (commonly referred to as psconsole) at http://hostname:portnumber/portal/psconsole.

Download and unbundle the sample portlet, which contains the helloi18nportlet.war file. The file structure is as follows:

Type File Suffix	Recommended Location
WEB-INF	web.xml portlet.xml fmt.tld
WEB-INF/classes/com/sun/portlet/i18n	HelloI18nPortlet.class HelloI18nPortlet.java HelloI18nPortlet.properties HelloI18nPortlet_fr.properties
WEB-INF/jsp	HelloI18nPortlet_view.jsp HelloI18nPortlet_edit.jsp HelloI18nPortlet_help.jsp HelloI18nPortlet_help_fr.jsp
dp	helloi18nportlet-dp.xml

Here are the key files:

• portlet.xml — This is the portlet deployment descriptor that defines the portlet title, the portlet mode (VIEW, EDIT, or HELP), the supported locale, and the resource bundle.
  
  
• HelloI18nPortlet.java — This is the portlet's main Java program that extends GenericPortlet and defines the do_View(), do_Edit(), and do_Help() methods.
  
  
• HelloI18nPortlet_view.jsp — This JavaServer Pages (JSP) page, used in the portlet's VIEW mode, displays the text field for the user input of a name and a welcome message.
  
  
• HelloI18nPortlet_edit.jsp — This JSP page, used in the portlet's EDIT mode, contains no data.
  
  
• HelloI18nPortlet_help.jsp — This JSP page, used in the portlet's HELP mode, displays the online help.
  
  
• HelloI18nPortlet_help_fr.jsp — This JSP page displays the online help in French.
  
  
• HelloI18nPortlet.properties — This is the resource bundle that contains the standard constants, as specified in JSR 168, for the portlet title and other resource messages displayed by the sample portlet.
  
  
• HelloI18nPortlet_fr.properties — This is the resource bundle for the French locale with messages in French.
  
  
• helloi18nportlet-dp.xml — This is Portal Server's display profile that creates channels in the Developer Sample for the portlet.

Internationalizing portlets involves three major steps: adding internationalization support for locales, to the portlet source, and to the portlet's online help. The procedures described in this section are those for internationalizing the sample portlet.

Adding I18N Support for Locales
To add I18N support:

1. In the portlet.xml file, specify, by means of the <supported-locale> tag, the locales you would like the portlet to support. For example:
   
   

   <portlet> ... <supported-locale>en</supported-locale> <supported-locale>fr</supported-locale> ... </portlet>

    
   
2. Declare the base resource bundle in the portlet.xml file with the <resource-bundle> tag. For example:
   
   

   <resource-bundle>com.sun.portlet.i18n.HelloI18nPortlet</resource-bundle>

    
   This bundle enables the Portlet Container to fetch the localized values for the title, the short title, the keywords, and the resource messages in the portlet. Also, during localization, the bundle specifies which resource bundle to localize.
   
   For details, see the sections on PLT.6.2 Portlet Resource Bundle and PLT.21.10 Resource Bundles in the JSR 168 Specification.

Now take a look at the fallback mechanism by which Portal Server determines the values for the portlet's title, short title, and keywords. The mechanism is as follows (in order of precedence):

1. If they are programmatically set by the developer.
   
   
2. If they are specified in the Display Profile.
   
   
3. If they are specified in the resource bundle with the standard constants, as defined in JSR 168 and JSR 286. The constants are as follows:
   
   
   • javax.portlet.title — The title that is displayed in the title bar of the portlet. Only one title per locale is allowed. This title can be overridden by the portal or programmatically by the portlet. For example:
     
     javax.portlet.title=Hello Internationalization Portlet
     
     
   • javax.portlet.short-title — A short version of the title that can be adopted for devices with limited display capabilities. Only one short title per locale is allowed. For example:
     
     javax.portlet.short-title=Hello I18n
     
     
   • javax.portlet.keywords — Keywords that describe the portlet's capabilities. Portals that allow users to search for portlets based on keywords can use these keywords. Multiple keywords per locale, separated by commas, are allowed. For example:
     
     javax.portlet.keywords=i18n,portlet

If none of the preceding conditions exist, Portal Server displays the portlet title, short title, and keywords as specified in the portlet.xml file.

If the portlet is minimized, Portal Server can still follow the preceding order in defining the title. However, in that case, Portal Server does not call the render or doView method and thus cannot obtain the value programmatically set by the developer.

Adding I18N Support to the Portlet Source
Adding I18N support to the portlet's source files involves a configuration of the JSP page and the Java program.

JSP Page
In the sample portlet, the JSP page HelloI18nPorlet_view.jsp supports I18N. Here are the steps to add that support:

1. Define the JSP tag library for internationalization, that is, fmt.tld. For example:
   
   <%@ taglib prefix="fmt" uri="/WEB-INF/fmt.tld" %>
   
   The tag library is bundled in the sample portlet.
   
   
2. Set up the resource bundle by defining the fmt:setBundle tag according to this syntax:
   
   <fmt:setBundle basename="package_name.resource_bundle_name"/>
   
   This resource bundle, loaded for the specified locale, loads resource messages. If Portal Server cannot find the resource bundle for a specific locale, it follows the standard Java locale fallback mechanism.
   
   For example, the tag in HelloI18nPorlet_view.jsp reads like this:
   
   <fmt:setBundle basename="com.sun.portlet.i18n.HelloI18nPortlet"/>
   
   
3. Fetch the messages from the resource bundle by defining the <fmt:message> tag according to this syntax:
   
   <fmt:message key="KEYNAME"/>
   
   This tag fetches the value associated with KEYNAME from the resource bundle. In the sample, the conventional non-I18N code reads like this:
   
   <INPUT type="submit" value="Submit">
   
   The I18N version, which contains the <fmt:message> tag, reads like this:
   
   <INPUT type="submit" value=<fmt:message key="submit"/>>

Similarly, add I18N support for the date and number formats, the time zone, and any other resources that can be internationalized. The sample portlet does not address those resources.

For details on internationalizing JSP pages, see Chapter 14 of The Java EE 5 Tutorial and the JSP Pages Standard Tag Library 1.1 Tag Reference.

Java Program
The sample portlet's main Java program, HelloI18nPorlet.java, in the doHelp() method supports I18N. Here are the steps to add that support:

1. Load the resource bundle with the getBundle function, which expects the locale as input. For example:
   
   

   rb=ResourceBundle.getBundle("com.sun.portlet.i18n.HelloI18nPortlet",request.getLocale());

    
   
2. Fetch the message from the resource bundle. For example:
   
   

   String helpFileName = rb.getString("helpFile");

    
   

Similarly, add I18N support for the date and number formats, the time zone, and any other resources that can be internationalized. The sample portlet does not address those resources.

For details on internationalizing Java programs, see:

• Internationalization, The Java Tutorials
• Articles: Internationalization and Localization
• Internationalization and Localization Code Samples

Adding I18N to the Portlet's Online Help
JSR 168 contains no specific approaches for adding I18N to portlet online help. This section describes the proven and clear approach adopted by the bundled portlets in Portal Server.

Each portlet must define the online help file name as a resource message in a resource bundle. In turn, each resource bundle for each locale defines the name of a unique online help file for a locale. For example:

• The HelloI18nPortlet.properties file contains this line: helpFile=HelloI18nPortlet_help_en.jsp
  
  
• The HelloI18nPortlet_fr.properties file contains this line: helpFile=HelloI18nPortlet_help_fr.jsp

You can name the online help files whatever you like because the file name is not a criterion for file lookup. Instead, the sample portlet relies on the standard resource bundle lookup mechanism to find the correct bundle (properties file), which identifies the help file. Nonetheless, for clarity, you should follow the convention format help_locale.jsp. For a portlet application that contains multiple help files for multiple portlets, use the convention help_portletname_locale.jsp.

The portlet looks up the file name with the ResourceBundle().getBundle(...).getString() method and includes the content in HelloI18nPortlet.java in the sample portlet, as follows:

public void doHelp(RenderRequest request,RenderResponse response
    ) throws PortletException,IOException{
    ResourceBundle rb =
ResourceBundle.getBundle("com.sun.portlet.i18n.HelloI18nPortlet",request.getLocale());
    String helpFileName = rb.getString("helpFile");
    if (helpFileName == null || helpFileName.length() == 0) {
        // assert
	throw new NullPointerException("null or empty page name");
    }
    response.setContentType(request.getResponseContentType());
    PortletRequestDispatcher dispatcher = getPortletContext().getRequestDispatcher(
        "/WEB-INF/jsp/"+helpFileName);
    dispatcher.include(request, response);
}

This section describes how the sample portlet is localized for the French (fr) locale. Here are the steps:

1. Add the supported-locale tag to the portlet.xml file. For example:
   
   

   <portlet> ... <supported-locale>en</supported-locale> <supported-locale>fr</supported-locale> ... </portlet>

    
   
2. Localize the resource bundle.
   
   The resource bundle in the sample portlet is called HelloI18nPortlet.properties. Correspondingly, the localized resource bundle for the fr locale is called HelloI18nPortlet_fr.properties, which contains the French translation for the English strings in the base resource bundle.
   
   The content of HelloI18nPortlet_fr.properties in the sample portlet reads as follows:
   
   

   # Standard Constant defined for Portlet Title, Short-title, Keywords javax.portlet.title=Bonjour internationalization Portlet javax.portlet.short-title=Bonjour I18n javax.portelt.keywords=i18n,portlet #Resource Messages used by portlet firstname=Prénom welcomei18n=Bienvenue au monde de l'internationalisation de Portlet back=Dos

    
   
3. Localize the online help.
   
   
   1. Add the helpFile property in the localized resource bundle with a value that points to the localized help file.
      
      Since the sample's localized resource bundle for the fr locale is called HelpI18nPortlet_fr.properties and the localized help file is called HelpI18nPortlet_help_fr.jsp, add this line to HelpI18nPortlet_fr.properties:
      
      helpFile=HelloI18nPortlet_help_fr.jsp
      
      
   2. Translate the base help file, that is, localize the content of HelloI18nPortlet_help.jsp to HelloI18nPortlet_help_fr.jsp.
      
      The English help file, HelloI18nPortlet_help.jsp, reads as follows:
      
      

      <%@page contentType="text/html"%> <%@page pageEncoding="UTF-8"%> <b>HelloI18nPortlet - Help MODE to get help about this portlet</b>

       
      The French help file, HelloI18nPortlet_help_fr.jsp, reads as follows:
      
      

      <%@page contentType="text/html"%> <%@page pageEncoding="UTF-8"%> <b>HelloI18nPortlet - MODE d'aide pour obtenir l'aide au sujet de ce portlet</b>

       
      

Next, deploy the portlet and add it as a sample of Portal Server:

1. Deploy the portlet's Web archive (WAR) file to Portal Server. Type, all on one line:
   
   % psadmin deploy-portlet -u uid -f password-filename {-g|-d dn} -p portal-ID WAR-filename
   
   For example:
   
   /opt/SUNWportal/bin/psadmin deploy-portlet -u amadmin -f /tmp/password -p portal1 -d "o=DeveloperSample,dc=india,dc=sun,dc=com" /tmp/helloi18nportlet.war
   
   For details on the command psadmin deploy-portlet, see Chapter 6 of Sun Java System Portal Server 7 Command-Line Reference.
   
   
2. In the Portal Server Administration Console, create the portlet channel and add it to a container in your portal. This article assumes that Portal Server is preconfigured with the Developer Sample.
   
   Alternatively, create the channel directly in the display profile (helloi18nportlet-dp.xml in the portlet's WAR file) in the command line according to this syntax:
   
   psadmin modify-dp -u uid -f password-filename {-g|-d dn} -m -p portal-ID filename
   
   For example:
   
   % /opt/SUNWportal/bin/psadmin modify-dp -u amadmin -f /tmp/password -m -p portal1 -d "o=DeveloperSample,dc=india,dc=sun,dc=com" /tmp/dp/helloi18nportlet-dp.xml

Finally, run the portlet and verify how it changes behavior as the browser's locale changes. Do the following:

1. Go to the Portal Server desktop at http://hostname:portnumber/portal/dt.
   
   
2. On the welcome page, click the Developer Sample link to go to the Developer Sample desktop for anonymous users.
   
   
3. Change the browser locale to fr.
   • In Mozilla, choose Edit > Preferences > Languages and change the locale setting.
   • In Internet Explorer, choose Tools >Internet Options > General > Languages and change the locale setting.
   
   
4. Log in to the Developer Sample of Portal Server by typing developer in both the User Name and Password fields.
   
   The Developer Sample is displayed in French.
   
   
5. Click the French version of the Portlet Samples tab.
   
   The sample portlet is displayed with the French title, Bonjour internationalisation Portlet.
   
   
6. Type your name in the Prénom text field and click Soumettre. See Figure 1.
   
   

   Figure 1: Sample Portlet

    
   The welcome message, addressed to you by name, is displayed in French, as in Figure 2.
   
   

   Figure 2: Welcome Page

    
   
7. Click Dos to return to the sample portlet.
   
   
8. Click the Help icon on the right of the title bar.
   
   The French version of the portlet's online help is displayed. See Figure 3.
   
   

   Figure 3: Online Help for Sample Portlet

    
   

Even though adding I18N and L10N support in portlets in Portal Server takes a few steps, the procedures are by and large intuitive and interesting. Internationalizing and localizing portlets greatly enhances portals for non-English-speaking users. Have a try.

• Sun Java System Portal Server
  • Main page
  • Developer home
  • Software Forum
  
  
• Open-source portal-related projects
  • OpenPortal
  • Portlet Repository
  • Portlet Container
  • WSRP
  • JavaServer Faces Technology-Based Portlet Bridge
  • NetBeans Portal Pack
  
  
• Weblogs and Community Wiki
  • The Portal Post
  • The Aquarium
  • Community Wiki
  
  
• Sun developer services
  • Support
  • Training and certification