Creating a Localized Portlet

A localized portlet, also referred to as an internationalized portlet, is one that displays its text, numbers, and dates in the correct language and format for the locale (country and language) setting that the user has selected. Users can specify their locale preference in the Web browser software or in the User Preferences option of the portal Web application.

To create a localized portlet, use these steps:

1. Create files containing translated messages.

2. Create display resources files containing translated titles and descriptions (optional).

3. Create an action class for the portlet.

4. Use internationalization tags from the JSP Standard Tag Library (JSTL).

Step 1: Create Files Containing Translated Messages

Place translations of your portlet's messages in resource bundles, which are files suitable for use by the Java ResourceBundle class. These files must be named with the extension .properties.

Create these files as follows:

1. Create a separate file for each language (or each country and language combination) that you need to support.

2. In each file, use <key>=<value> statements to define the text strings. Use the same key names in each file.

   If a message does not require translation, you can omit it. For example, if the default locale is U.S. English, some messages might not require translation to British English. These messages can be omitted from the British English resource bundle, and the default U.S. English translation will be used.

3. Name the files as follows:

   • Use the same base name for each file (for example, Resources).

   • Append each file's base name with the appropriate locale identifier (for example, _en_US for U.S. English, _fr_CA for Canadian French, and so on). The file for the default locale does not need to have a locale identifier.

   • Give each file name the extension .properties.

   For example, if the default language and country is U.S. English, you could create the following:

   • a file called Resources.properties that contains U.S. English messages

   • a file called Resources_fr_CA.properties that contains Canadian French messages

   • a file called Resources_uk_EN.properties that contains British English messages

4. You can place all of the files in the package of your choice. Since the files must be included in the PAR file, it might be convenient to place them in the package where the portlet's action class will be located.

For more information on resource bundles, refer to the internationalization information on the Sun Web site at http://java.sun.com.

Step 2: Create Display Resources Files Containing Translated Titles and Descriptions (Optional)

The resource files created in Step 1 affect only the text that is displayed inside of the portlet. They do not affect the metadata (including the title and description) that describes the portlet. The SAS Metadata Repository cannot store multiple, localized values for metadata. Therefore, the portlet title and description cannot be translated based on the user's locale preference.

However, the portlet title and description can be translated into the portal Web application's default locale at the time that the portlet is deployed. To make this happen, you must place translated titles and descriptions for your portlet in portletDisplayResources.properties files.

When the portlet is first deployed, the deployment process will check to see which default locale was specified when the portal Web application was installed. Based on this locale, the deployment process uses the title and description from the appropriate display resource file to create metadata and register the portlet in the SAS Metadata Repository.

Note: If your portlet will be deployed in only one locale (language), this step can be omitted. If you do omit this step, the portlet deployment mechanism will send a warning message to the server log that no localized title or description can be found. In addition, you will not be able to specify a description for your portlet. Instead, the portal Web application will use the portlet's name to create a default description.

Create the display resources files as follows:

1. Create a separate file for each language (or each country and language combination) that you need to support. In each file, use <key>=<value> statements to define text strings for portlet.title and portlet.description, as in the following examples:

   portlet.title=Welcome Portlet
   portlet.description=Welcome Portlet
   
   portlet.title=Portlet de bienvenida
   portlet.description=Portlet de bienvenida

2. To name each file, use the base name portletDisplayResources. Append each file's base name with the appropriate locale identifier(as described in Step 1-c previously) and then with the extension .properties.

3. Place the files in the /portletname/classes directory of the PAR file.

Step 3: Create an Action Class for the Portlet

Create an action class for your portlet, as follows:

1. Import the com.sas.portal.portlet.NavigationUtil class.

2. Add the following code to the service() method of your action class, with the correct package and name for your resources, as in the following example:

   NavigationUtil.prepareLocalizedResources( "com.mycompany.portlets.Resources", request, context);

   This method uses the portlet classloader to obtain the resource bundle from the portlet's PAR file. It then uses the bundle and the locale of the current user to make a new JSTL localization context. The localization context will be available to your portlet's JSP page.

Step 4: Use the Internationalization Tags from the JSP Standard Tag Library (JSTL)

When you create the portlet's JSP page, use tags from the JSP Standard Tag Library to display text, as follows:

1. First, include the taglib directive for the JSTL formatting tags:

   <%@ taglib uri="http://java.sun.com/jstl/fmt" prefix="fmt"%>.

   The directive must appear before the first use of these tags.

2. To display a text message from the resource bundles, use the message tag with the key attribute, as in the following example:

   <fmt:message key="welcome.msg1.txt"/>

   This example will obtain text associated with the key welcome.msg1.txt from the resource bundle for the locale that most closely matches the user's locale preference.

You can also use the other JSTL tags for formatting such locale-sensitive items as dates and currency. The portal Web application makes the user's locale available to those tags.

For more information about creating JSP pages for portlets, see Developing the Presentation JSP Page. For information about JSTL, refer to the Sun Web site at http://java.sun.com/products/jsp/jstl. The JSTL jar files are provided with the SAS Web Infrastructure Kit.