Implementing multilingual sites using IBM Workplace Web Content Management in IBM WebSphere Portal

With IBM Workplace Web Content Management, you can build sites that serve content in different languages. Combined with the capabilities of the underlying IBM WebSphere Portal personalization engine, Workplace Web Content Management can deliver content that is personalized based on user preferences.


Ahmed Abbass (, IT Architect, IBM

Ahmed Abbas is an IT Architect at Cairo Technology Development Center. Through his involvement in lab services, Ahmed has been interested in bridging the gap between the theories behind technology and the practicality of implementations to serve customer business needs. You can reach him at

Hebba Soliman (, Senior Software Engineer, IBM

Hebba Soliman is a senior software engineer at IBM Cairo Global Delivery Center (C-GDC). She has extensive experience in developing and designing Web applications using IBM Workplace Web Content Management and personalization.

29 January 2008

Also available in Russian Japanese

Browsing multilingual sites may be an interesting experience for Web users who regularly see all content in their own language. If your portal provides content in different languages, though, you need to deliver the content according to users' preferred language. Furthermore, if your portal provides a variety of categorized contents, you may need to deliver content that accommodates user preferences. Both user preferred language and interest areas can be captured at registration time. Refer to the "Resources" section for links to useful resources on customizing IBM WebSphere Portal login behavior.

Readers should be familiar with IBM WebSphere Portal V6.0 administration and its components, IBM Workplace Web Content Management, and the personalization engine.

To demonstrate this idea of personalizing content, the article uses an example of a portal that provides content in English and in Arabic. The same concept can be applied to more than two languages and to languages other than those used in the example. The example is a news portlet that lists headlines that point to a News Details portlet. The two portlets are shown in figure 1.

Figure 1. The news portlets when rendered in English
The news portlets when rendered in English

When the same portlets are rendered in Arabic, they appear as shown in figure 2. Note that the right-to-left orientation is automatically handled by WebSphere Portal based on the user language.

Figure 2. The news portlets when rendered in Arabic
The news portlets when rendered in Arabic

Now, let's see the idea behind the implementation before we examine the detailed steps.

How does it work?

An important aspect of designing a multilanguage site is organizing content in a way that simplifies both its authoring and retrieval during rendering. The design discussed here allocates a separate site area and an authoring template for each language. Because the example has two languages, Arabic and English, there are two site areas and two authoring templates.

The language of each content item is determined by the site area to which it belongs. On another dimension, the same content item can be associated with one or more interest areas represented by a taxonomy and the categories underneath it.

Page language is specified according to the locale of the user upon entry or according to the user's preferred language stored in his profile. By having the content organized this way, content items can be filtered based on user language and interest areas that are provided at runtime as shown in figure 3.

Figure 3. Content filtering based on user language and interests
Content filtering based on user language and interests

For registered users, user language and interest are typically retrieved from the user profile. Refer to the "Resources" section for more information on retrieving user preferred language from a logged-in user profile. The same design here can still work if user language and interests are programmatically supplied otherwise.

There are two alternative ways to implement the rendering part that actually does the filtering. The rendering part can be implemented as either of these components:

  • A menu component for each language. A JSP component can be used to select the menu component according to the locale of the user to display the list of contents.
  • A personalization component for each language. Personalization rules determine the personalization component to be used based on matching the user language with the authoring template associated with a content item. The same rule can perform filtering based on user interest (stored in the profile) as well. This alternative utilizes the WebSphere Portal personalization and the Workplace Web Content Management capabilities.


This section shows the steps you take to implement the solution for navigating between languages based on preferred language. The first part discusses the creation of the Workplace Web Content Management artifacts that are common to the two rendering options covered by the second part of the implementation steps.

Workplace Web Content Management artifacts

Using WebSphere Portal administration, you create the artifacts as shown in the steps that follow, or you may use an existing equivalent of each one of these artifacts and skip this section. The names of the artifacts are mentioned only for cross-referencing purposes.

Content library, site, site areas, and workflows

Create a Workplace Web Content Management content library called MultiLanguage. In this library, create a site and name it MultiSite. Then, create a site area for each language under that site, HomeEnglish and HomeArabic. Choose an internationalized display name for the Arabic site area as shown in figure 4.

Figure 4. Created library, site, and site areas
Created library, site, and site areas

Now, create another site area under each of these newly created site areas to contain the content rendered by the example: News. Because the News site areas have two different parents, they can have the same name while having different localized display names for each language.

To publish content, define workflow stages and the workflow that the news content items use. A simple one-stage workflow is sufficient for the example. Create a workflow stage by choosing New - Workflow stage, name it Publish stage, and choose the publish action for this stage.

Next, create a workflow by choosing New - Workflow, and then name it One Stage Workflow. Select the Select Workflow Stage option, and then select the just created stage called Publish stage.

Authoring and presentation templates

To author content items, you create an authoring template that represents the news details for each language: at_news_en and at_news_ar. Create an authoring template by choosing New - Authoring Template. Select the Manage Elements option, select an Element type for the field, and then click Add. As an example, the list shown in table 1 was used. Using the Element Manager, add the fields shown in table 1 to both templates.

Table 1. Authoring templates' fields
Element type NameDisplay title
Rich textrtf_descriptionrtf_description
Component referenceImg_newImageImg_newImage

Associate the workflows created in the previous section to their corresponding authoring templates created here.

For the rendering part, define a presentation template pt_newsDetail. The News Details page source is shown in listing 1. The elements shown in the page source are in a table, but it is omitted for readability.

Listing 1. The source code for the News Details page
<Element context="current" type="content" key="txt_title" /> 
<Element context="current" type="content" key="img_newsImage" />
 <Element context="current" type="content" key="rtf_description" />
<!-- links to the News List page created with the URL mapping as a back link -->
<a href="<PathCmpnt type="noprefixbase" start=" "
			end="/wps/myportal/NewsList" />"> <-- </a>

The templates are ready to be mapped to their corresponding news site. In the English news site area, click the Edit Template Mapping button and choose at_news_en as the authoring template and pt_newsDetail for the presentation template as shown in figure 5. Do the same for the Arabic news site area but select at_news_ar as the authoring template as shown in figure 6.

Figure 5. Template mapping for the English News site area
Template mapping for the English News site area
Figure 6. Template mapping for the Arabic News site area
Template mapping for the Arabic News site area

From a presentation standpoint, the News List page rendering is covered by the following section that discusses the rendering options.

Image component

The News Details page of the example shows an image. To avoid uploading the image twice – one for each site area or language – you can create an image component, so that each content item created under both site areas refers to the same image component.


Now that you have created the Workplace Web Content Management artifacts, you can start authoring content items, which are pieces of news with a title, a description, and an image. You need this content to preview the rendering part that comes next.

This section describes the two rendering options for the News List page: using menu components and using the personalization components.

Using menu components

The News List page can be implemented as a menu component that you create for each language: menu_newsList_en and menu_newsList_ar. Each of the created menu components retrieves content by its authoring template or the site area it belongs to as shown in figure 7 for the English version. The Arabic version uses its corresponding artifacts created for the Arabic language.

Figure 7. The menu component created for the English News List page
The menu component created for the English News List page

You can then add a header and footer to the design section of each of the menu components. For the search result, include placeholders for the title and description fields to be substituted by their values in the rendered content item as shown in listing 2. At the end of the listing, there is a link to show more news headlines.

Listing 2. Design for each menu search result
<a style="color: rgb(0, 0, 0); font-size: 14px; font-weight: bold;" 
href="<Placeholder tag="href" start="" end=""/>"> ** <FONT 
color="blue"><Element context="autoFill" type="content" 
key="txt_title"/></FONT> </a>
<Element context="autoFill" type="content" key="rtf_description"/>
<a href="<Placeholder tag="href" start="" end=""/>">More</a>

The menu components are ready to be consumed by a JSP component. Create the JSP component with the name jsp_DisplayNewsList and let it point to a JSP file whose path is /jsp/html/gettingNewsContents.jsp. Accordingly, the physical path of the JSP file would be in a directory similar to:

<websphere portal installation path>\installedApps\

Refer to the WebSphere Portal V6.0 Information Center for more information on JSP component creation.

Now, create that JSP file and include the code shown in listing 3.

Listing 3. The JSP file that uses the menu components to render content
<%@page language="java" contentType="text/html; charset=ISO-8859-1"	
pageEncoding="UTF-8" session="false"%>
<%@page import="*,*"%>
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
<%@ taglib uri="/WEB-INF/tld/portal.tld" prefix="wps" %>
try {

	//Connect to WCM Workspace
	Workspace workspace = WCM_API.getRepository().getWorkspace("username", "password");
	//Set it to the library that you have created for the example
	//Get user language from the request and 
	//according to the language, it chooses the correct menu component by name
	String language  = request.getLocale().getLanguage();
	//The example does not consider the case when no language is found 
	//in the request. For a real implementation, you may need to handle that case.
	if(language  != null){
	//Set the menu component according to language
		String compName = "menu_newsList_" + language ;
		//Retrieve the menu component
		DocumentIdIterator docIds = 
		if (docIds.hasNext()){
		  DocumentId did = (DocumentId);
		  LibraryComponent libComp = (LibraryComponent)workspace.getById(did);
		  //Get the rendering key from the request
		  RenderingContext rcjsp = 
		  //Now, render the personalization component and output the resulting html!
	 	  String html = workspace.render(rcjsp, libComp);
catch (Exception e) {
	//For a real implementation, you may need to handle exceptions in a 
	//more advanced way. The basic handling below is just an example.
	out.println("exception = "+e.toString());

You should give security permissions to the components and contents you created. To run this example, you can use any member of the wcsadmins group.

Using personalization components

An alternative to menu components is personalization components that use the WebSphere Portal personalization engine. Using personalization rules, content can be filtered by both language and the user's interest areas at the same time.

First, create a taxonomy that contains business categories resembling the different interest areas as shown in figure 8. Include Education, Health, and Sports as categories.

To create a taxonomy, choose New - Taxonomy and name it Interest. Next, create the categories by choosing New - Category. Choose the parent taxonomy to be Interest.

Figure 8. Interest areas implemented as categories under taxonomy called Interest
Interest areas implemented as categories under taxonomy called Interest

The categories you defined can be associated with content items in the User Profile section to designate the interest areas to which these items belong. To access the profile page, go to Administration page - Launch - Edit My Profile. You may edit the user profile of the user account you are using to set the interest areas; you do so by editing the businessCategory field with the same interest category name. Make sure that you have created content items that are associated with the category that you assigned to the user so that you can see matching results while rendering.

Now create action rules that are used to filter the content. You need a rule for each language: UserInterestContents_en and UserInterestContents_ar. To create a new rule, navigate to Administration page - Launch - Personalization, and then select New - Rule. Select Select Action as the rule type.

Each rule should use the artifacts created for its corresponding language as shown in figure 9 for the English language personalization rule.

Figure 9. The personalization rule that retrieves English content based on user interest areas
The personalization rule that retrieves English content based on user interest areas

The value of the site area is left empty, and filtering is based only on the authoring template and the interest category.

What you need now is a personalization component for each language to use the personalization rules that you have just created. Name them pers_NewsList_en and pers_NewsList_ar.

As you create the personalization component, choose the created rules in the Personalization Element section. In the design section of these personalization components, reuse the design section that you created for the menu components.

Again, as you did with the menu components, you create a JSP component that uses the personalization components you created here. That JSP component refers to a JSP file that looks like the JSP file you created for the menu, but with this change:

//Set the personalization component according to language
String compName = "NewsPersonalizedList_" + language ;

WebSphere Portal pages

After applying one of the rendering options, you create the portal pages containing the rendering portlets to view the list of news items and the detailed page of the news item selected from that list. In WebSphere Portal administration, create the two pages, NewsList and NewsDetail. Add the Web Content Viewer portlet to each page. For easier navigation between the two pages, you may create a URL mapping for each one: News List and News Details. Figure 10 shows the details of each page.

Figure 10. The details of the created portal pages
Figure 10. The details of the created portal pages

Default content has been set to English content, but it does not matter which content is chosen.

The component used in the News List page is the JSP component you created, jsp_DisplayNewsList, either for the menu component or the personalization component. The target portal page field of the News List page points to the News Detail page. In its turn, the News Detail page uses the target portal page field to point back to the News List page.

Now, the example is ready to run. View the News List page to view the list of news that you entered under the language and the interest of the logged-in user.

Design considerations

In this section, we discuss some important aspects about the design implemented by the example used, including best practices to use or to modify the design for better maintenance and performance.

Supporting more languages

This design simplifies the process of supporting additional languages by the site. All you need to do is add a new site area to hold the artifacts created for the new language along with an authoring template and menu component or personalization component.

To switch between the languages, the user should change the locale of the browser or change the user preferred language from the Edit My Profile page. Also, if the content author for each language is a different person, you can use access control to assign different authors for different site areas; that is, you can assign an author for each language.

Filtering options

Filtering by authoring template in personalization rules instead of filtering by site area usually leads to better performance.

Simplifying content authoring and maintenance

The more fields you have in your authoring template, the more useful this design is. Having a different authoring template with fields to represent each language is easier to maintain than having one authoring template with all fields for all languages.

Optimizing the usage of Workplace Web Content Management APIs

The design adopted here relies on associating content to templates and components, thereby eliminating the need of the JSPs to use the APIs that search content in the Workplace Web Content Management repository.

For other cases, if you need to add a search in a JSP file, use the method workspace.contentsearch(), which takes a separate authoring template and a separate site area as parameters. This method has a better performance than looking for content using a search by authoring template and then filtering the results by site area. On the other hand, personalization rules perform better when the method retrieves content by authoring template rather than by site area.


Supporting multilingual portals is made easy by the built-in capabilities of WebSphere Portal through its Workplace Web Content Management and personalization components. In this article, you have seen how to make your portal deliver content based on both user preferred language and user interest areas.


The authors would like to express gratitude to Maha Abdel-Qader and Hassan Ali for their support in the early stages of the project. And special thanks goes to Hala Aziz, Ahmed Khairy, Kareem James, Mohab el-Hilaly, Mohamed Maher, and Mourad el-Badry who took time out of their busy schedules to review this article and provide their comments.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

Zone=WebSphere, Lotus
ArticleTitle=Implementing multilingual sites using IBM Workplace Web Content Management in IBM WebSphere Portal