Adding new languages to your IBM WebSphere Portal implementation has cultural as well as technical aspects. WebSphere Portal V6.1 has formal support for 31 languages. These languages and their ISO 639 language codes are listed in table 1.

Adding new language support involves a translation exercise for WebSphere Portal's user interface subject matter. You must consider the following cultural questions and their impact:

• Does an appropriate term exist in use in the target language? Consider the term "login"; this term derives from a period in western industrial history when a factory worker would stamp a time sheet or card upon arrival. If the language you are translating to is used in a culture in which this action never had common use, because alternative methods of time recording were used, or because the society has no legacy industrial heritage, it might prove difficult to find an appropriate local term.
• Does the organization providing the translation require or want external approval for the translation of terms? When an educational or government organization is the first to provide new terms, there is often a desire to obtain widespread community consent before the terms can be sanctioned for use in the portal. Gaining this consent can prove a time-consuming process.
• Has the organization committed to managing the new language implementation elements as part of their portal's release strategy, and does it have a governance process for extending the support provided for language terms as multilingual portlet applications are developed and deployed? To achieve consistency, terms should, as far as possible, be moved into a single resource.

These matters affect the success of the deployment as much as the technical aspects that are covered here. We now move to consider the technical aspects of language implementation.

Back to top

Expressing a language preference in the header

Before considering WebSphere Portal, let's review how a Web client encodes language preference in a request. Language preferences, specified by RFC3066, are most easily expressed using comma-delimited language tags in the Accept-Language HTTP request header. A language tag is composed of one or more components: a primary language component and a possibly empty series of country components. The primary component is an ISO-639 language abbreviation; any two-letter country component is an ISO-3166 country code. A locale is a unique combination of a language and a country or location. Client requests can specify these language tags in the Accept-Language HTTP header (as defined in RFC2616). This header is potentially quite sophisticated, as shown in this example:

Accept-Language: fr, en-gb;q=0.8, en;q=0.7

To an application receiving a header and coded to provide the most appropriate content, this code means "First there is French, but will accept British-localized English and other types of English." The optional "q" (quality) attribute can be used to indicate a preference between versions of an acceptable language. NOTE: According to the specification, the order of languages in the header in the comma-separated list is not significant; all languages that are assigned a quality factor greater than 0 are considered acceptable. The principle of personalization means that the WebSphere Portal application attempts to find the most appropriate or specific resource to match the user's request, which means that a user's language or locale preferences are an important consideration.

Setting the default language for a browser client is client-specific; some browser clients are, or can be, bound to the operating system's language setting, while others allow language support to be defined as a preference. For testing, we found the LocaleSwitcher Firefox add-on to be useful.

Accept-Language is the third method used by WebSphere Portal to determine a language preference. WebSphere Portal looks first for a language preference encoded in the URL, and then in the user's profile. If there is no preference found in these areas, the Accept-Language header is used. For simplicity, our client decided to use this option, which allows users to change the language by changing the browser language preference. The reasons for this choice are as follows:

• Changing the language preference this way was an existing practice that was well understood by the client's user base.
• URLs were considered too volatile to carry the language preference consistently.
• The user profile (with language coming from a single attribute in the directory) was considered too immutable or difficult to change to deliver the flexibility that was required.
• Visibility rules for showing Welsh- or English-language portlets based on the browser's language attribute were to be used.

Back to top

Adding to the set of supported languages

When adding support for a language, your first task is tell the portal application about the language so that it can provide it as a choice when, for example, setting the titles and descriptions of portlets (in this case, the Manage Portlets window), so that the title and descriptions appear appropriately by language. See figure 1.

The Websphere Portal XML configuration interface (XMLAccess) can be used to create new language definitions. The XML input to the xmlaccess utility program shown in listing 1 creates the new language, Welsh.

<?xml version="1.0" encoding="UTF-8" ?>
<request     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"
      type="update">  
	<portal action="locate"> 
      <language action="update" bidi="false" domain="rel" locale="cy_GB">
        <localedata locale="cy">
          <title>Cymryg</title>   <!-- Welsh for Welsh -->
        </localedata>
          <localedata locale="en">
            <title>Welsh</title>	  
            <!-- English (default locale) for Welsh -->
            </localedata>
		</language>
	</portal>
</request>

When a language is added using the XMLAccess interface, there are three minimum data requirements, which you can see in the xmlaccess input above:

• A language identifier. This identifier is equivalent to the language tag in a request header. In the example above, this identifier is the value of the locale attribute of the language element.
• The name of the language in the locale's language (for example, for the Welsh language, "Cymryg"). In the example above, this data is the value of the title element whose parent element's locale attribute is the language code (for example, "cy").
• The name of the locale in the portal's default language. For example, for a portal with a default locale of en (English), we need the word in English for Welsh, which is, unsurprisingly, "Welsh." In the example above, this data is the value of the title element whose parent element's locale attribute is the default language code (for example, "en").

For completeness, a localedata element, similar to one for locale="en" above, would be provided for all supported languages. In practice, resources tend to favor support for the languages of administrators only.

When adding content for the language, you should consider two main areas of globalization:

• The translation of screen prompts, button text, and so on
• The translation of narrative content, such as the content of help files

These two areas have to be addressed in a similar manner for any portal application, including the WebSphere Portal server application itself, which is the focus of this article.

Back to top

Providing translation of screen prompts

The administrative interface needs to be able to translate resource keys (such as the word "Login" or the expression "Title") to the new language.

We follow the standard Javaâ„¢ 2 Platform, Enterprise Edition practice of globalization by resource bundles here. The process requires the creation and deployment of a new set of files to support the language and their placement on the WebSphere Portal application server's classpath. The standard support is provided in ${WP_ROOT}/shared/app/wp.ui.jar. When you unpack this JAR file, you find an nls folder that contains files for each of the administrative domains, suffixed with the language and locale codes.

As a recap, each line of each file contains a key, common across all the files used in the application's presentation tier, and the translation of that key to the appropriate language and locale represented by the file. For example, problem_short_fr.properties lists the short messages reported to the window when a problem occurs and the portal user is a French speaker. For example, the line in the file:

password.invalid = Mot de passe incorrect.

shows the message used when the user's offered password is incorrect. You might also consider that this support is provided for all French-speaking users, regardless of the locale that they might offer to refine their preference. Examining the files in the nls folder further, you can see that there are two types of files supporting speakers of Portuguese: problem_short_pt_BR.properties and problem_short_pt.properties. The latter type provides short error messages for all Portuguese-speaking portal visitors, and the former type (used if the user's Accept-Language preference can be matched to pr_BR instead of BR) delivers messages in Brazilian Portuguese.

To see how these keys are used in the WebSphere Portal application, examine Login.jsp (on most installations, it is located at ${WP_PROFILE_ROOT}/installedApps/${cell_name}/wps.ear/wps.war/screens/html). Listing 2 shows an excerpt from this JSP file, which handles the Login presentation duties when a window is being used for Login.

<%-- Login/Cancel buttons --%>
<table cellspacing="4" cellpadding="0" border="0" width="100%">
	<tr>
		<td align="<%= bidiAlignLeft %>" valign="bottom" nowrap>
			<input class="wpsButtonText" type="submit" 
			value='<wps:text bundle="nls.button" key="login" />'>
		</td>
		<td align="<%= bidiAlignLeft %>" valign="bottom" nowrap>
		</form><form method="POST" action="<wps:url home='public' 
		reqid='no'/>" enctype="application/x-www-form-urlencoded" 
		name="CancelLogin">
			<input class="wpsButtonText" type="submit" value='<wps:text 
			bundle="nls.registration" key="button.cancel" />'>
		</td> 
...

You can see in listing 2 that the value of the login key from the nls.button bundle of messages is used as the text on the Login submit button. In practice, that means that the best matching button properties file from the folder nls is selected from the wp.ui.jar file for the user's language preference. The best matching file name is determined by adding a suffix underscore (_) plus the user's language preference to the bundle's name ("button"). In the case of no match (in other words, in the case of a user with an unsupported language preference), the WebSphere Portal default language is used in the suffix. The same approach is applied to the Cancel button text in the second example in listing 2, which uses a different bundle and key.

NOTE: From WebSphere Portal V5.1, the <wps:text/> tag is still supported, but it is deprecated in favor of using the <i18n:bundle/> and <i18n:message/> tags of the JSP Standard Tag Library (JSTL).

To support a new language, you need to create the appropriate bundle files and make them available on the WebSphere Portal application server's classpath.

Back to top

Creating the new language files

You can create the new files most easily by expanding the JAR file to a temporary location and copying an existing set to create new files, each with a "_cy" suffix. Then you must edit the files to provide translations of the value for each of the message keys (remember that the keys themselves are never translated) to the target language or locale. This process can be lengthy; social protocols for determining authoritatively the exact translation of some of the keys are sometimes time-consuming. The next step is to ensure that the file is encoded with the ASCII code page, using a Java SDK utility called native2ascii, which can be found on standard WebSphere Portal installations at ${WAS_ROOT}/java/bin/native2ascii.

Back to top

Collaborative tooling considerations

If the WebSphere Portal environment is hosting IBM Lotus® collaboration products such as IBM Lotus Quickr™, IBM Lotus Domino® Web Access, or IBM Lotus Sametime®, you need to take an additional step. Language support in the messages and prompts of these products is done by means of individually deployed resource bundle files, stored on the file system (in standard installations) at ${WP_ROOT}/shared/app/nls. The files are prefixed "CSRes_".

Back to top

Deploying the files to the server's classpath

You have options for deploying the translated files for the new language:

• You can package the new files into the existing wp.ui.jar file.
  
  

  Repackaging the files into the wp.ui.jar file has the disadvantage of rendering wp.ui.jar non-standard, but it risks loss of new language support if a fix pack is applied that replaces the wp.ui.jar file. This method is not a practice that we recommend.

• You can copy the files to the ${WP_ROOT}/shared/app folder into "nls" folder.
  
  

  Message bundle files deployed to this folder augment (and, in the case of naming collisions for message keys, take precedence over) those loaded from the wp.ui.jar file. For development, this option is a quick way to check incremental development of the support for the new language. A neater deployment approach, though, is to package the files in a JAR file. As the language support forms part of a release, deployed through an automated release process, deploying individual files is not recommended.

• You can create a new JAR file and deploy the file to ${WP_ROOT}/shared/app folder.
  
  

  This folder is on the WebSphere Portal application server's classpath, and all files ending with "jar" in this folder are loaded by the server at startup. Therefore, if a new JAR file, containing the files in an appropriate nls folder, is deployed to ${WP_ROOT}/shared/app, it is loaded by the server on the next restart.

  NOTE: Some administrators might prefer not to deploy custom JAR files to ${WP_ROOT}/shared/app. In this case, another alternative is to deploy the JAR file to any acceptable physical location on the server and to administratively add the location to the WebSphere Portal server's classpath using the WebSphere Application Server console. http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/cagt_fileservices.html

Back to top

Deployment and release management

Adding a language adds to the WebSphere Portal release payload and modifies its configuration. If all servers in a cluster or cell share a release database (as is recommended for resilient portal infrastructures), then the language is available across the cluster or cell after the xmlaccess process has been run on any of the nodes. Language JAR files must be deployed correctly; the two methods of achieving this result are to use Network Deployment's file system synchronization service and to ensure that the automated deployment process for a release individually copies the correct language support JAR files that have been added to all servers. Note that for the changes to take effect, WebSphere Portal should be restarted after the deployment.

Back to top

Conclusion

Adding a new language to WebSphere Portal is a technical challenge of relatively low complexity. If the cultural and governance issues are addressed with the technical ones, success can result in significant benefits for the portal's adoption by users.

Resources

Learn

• Read more about language selection in WebSphere Portal.
  
  
• Read more about the file synchronization service in WebSphere Portal.
  
  
• Refer to the ISO639 standard.
  
  
• Refer to the RFC 3066 standard.
  
  
• Refer to the RFC 2616 standard.
  
  
• Learn about the the native2ascii utility.
  
  

Get products and technologies

• Download the Firefox LocaleSwitcher add-on.
  
  

Discuss

• Participate in the discussion forum.
  
  

About the authors

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Expressing a language preference in the header
• Adding to the set of supported languages
• Providing translation of screen prompts
• Creating the new language files
• Collaborative tooling considerations
• Deploying the files to the server's classpath
• Deployment and release management
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into WebSphere on developerWorks

Securing WebSphere Application Server environments

Essential resources to design and develop your WebSphere solutions in ways that will make them more secure.

Special offers