Localising Portlets

Localizing Portlets with IBM WebSphere Portlet Factory 10/5/2006 © Copyright International Business Machines Corporation 2006. All rights reserved. This article with the accompanying sample demonstrates how to use IBM® WebSphere® Portlet Factory Version 6 (hereafter called Portlet Factory) to localize portlets. It is intended for portlet developers writing portlets that must support multiple languages. This article is one in a collection of articles and samples that illustrate techniques for developing with Portlet Factory. See the Portlet Factory Product Documentation page for a complete list of these. For an introduction to developing with Portlet Factory, you should complete the introductory tutorials that are available both in the product help and on that web site.

Prerequisites You should have a basic familiarity with Portlet Factory and be able to create and run Portlet Factory models. You will also need to be able to create a test user whose preferred language is French.

Introduction to Portlet Localization Portlets and web applications that serve an international audience often need to be translated into several languages. J2EE platforms support translation efforts by automatically substituting pre-translated files based upon the active user’s locale preference. This concept is known as “localization”. Localization is generally implemented using the following techniques.

Localization Techniques One localization technique is to mark text strings in such a way that their translations can be substituted programmatically from a text file called a Resource Bundle. Strings marked in this fashion are said to be externalized strings. This technique is very common and is most useful when translating UI components such as button labels, menu choices, and list choices found in select lists, radio buttons, and checkboxes. Static text for field labels and short instructions or explanations is also often localized in this manner. Externalizing strings into Resource Bundles works best when the strings are short. Another technique is to create translations of entire HTML or JSP pages. This technique works best when there too much content for the previous technique to be practical. A portlet’s Help page is a good example as it may contain several paragraphs of instructions and other information. In these cases, the strings are simply too long to use Resource Bundles. The user’s locale preference is used to drive which version of the page is presented.

Implementing Localization The Localized Resource builder is the cornerstone to implementing localization using WebSphere Portlet Factory. It is necessary to use a Localized Resource builder call in any model that includes translations. This builder references a Resource Bundle in the web application project and uses that resource to create a variable named LocaleData. This variable is essentially an XML representation of the referenced Resource Bundle. Other builder calls in the application that rely on the contents of the Resource Bundle get their data from this variable. Resource Bundles are either text files with .properties extensions or Java classes. These files are found in the WEB-INF\work\source folder in the web application project. Text Resource Bundles contain name-value pairs where the names match the resource key names of the externalized strings and the values contain the language-specific translations of these strings. WebSphere Portlet Factory has several mechanisms for associating the resource keys in a Resource Bundle with UI components in portlets. This sample explores the most common of these mechanisms. Another important element of localization is the Profile Set named com.bowstreet.profileset.SimpleLocaleValues.pset. This Profile Set ships with Portlet Factory and contains a Profile Values Handler that relies on the user’s locale preference to determine the correct language and country codes to apply to the Localized Resource builder call. It is essential that the Language and Country inputs of the Localized Resource builder call are associated with the LanguageCode and CountryCode Profile Entries in order for the Profile Values Handler to work properly.

File Naming Conventions For localization to function properly, certain conventions must be followed. Each language has an internationally recognized language code. Since some languages vary by the countries in which they are spoken, internationally recognized country codes are used. Resource Bundle file names must have the correct language and country codes appended to their file names. Translated HTML and JSP pages must be stored in folders whose names are the correct language and country codes. Languages spoken in more than one country, or locale, have a default locale. For example, if the language code used is fr and no country code is supplied, the assumed locale is France as France is considered to be the dominant locale for the French language. If the intent is for the application to be translated into both French and Canadian French, the country code CA would need to be included in the Resource Bundle file names and the folder names containing the Canadian French translations, i.e. fr_CA.

Translating Entire Pages As described above, a common technique for implementing localization is to translate entire HTML pages and rely on the user’s locale preference to determine which version of the page to use. Certain Portlet Factory builders lend themselves well to using this technique.

Imported Page builders bring HTML pages into models. When these pages are translated in their entirety, the Localized Resource builder looks for the translations in folders beneath the location of the source HTML page. The folder names must follow the naming conventions described above. This sample has a help page in the samples/multi_language folder. The translations of this help page are stored in the sub-folders /en and /fr which are beneath the samples/multi_language folder. Portlet Adapter builders can declare which file is the Help file for the portlet. If the portlet also contains a Localized Resource builder call and there are language version folders beneath the folder containing the Help file, the user will see the locale-specific version of the Help file in the portlet.

Applying Localization to High-Level Builders Builders such as Data Page and View & Form can leverage the artifacts generated by a Localized Resource builder call to affect localization. Data Page can refer to the LocaleData variable created by the Localized Resource builder call and a specific page in the model. For every named element on that page whose name matches an element in the LocaleData variable, the language-specific value for that resource key will be substituted. View & Form has an input labeled Resource Bundle Name. This input refers to the Resource Bundle containing the resource keys and values for the named elements in the schema used by the View & Form builder call. For example, if the View & Form builder call presents rows of data returned by a service call, and the field names in the data match the resource key names in the referenced Resource Bundle, View & Form can perform the necessary locale-based string substitutions to translate field labels and column headings. The critical element is that the resource key names in the Resource Bundle match the schema element names in the schema View & Form uses to present the data. View & Form can also use indirect references to resource keys defined in the Resource Bundle via the LocaleData variable. View & Form can generate buttons such as Submit and Cancel. The labels for these buttons come from builder call inputs. If these inputs use indirect references, the button labels can be localized. For example, a Cancel button’s text label could be set to ${Variables/LocaleData/Data/page_cancel}. In this case, the label for this button will contain the localized string for the resource key named page_cancel. This resource key is found in the LocaleData variable, which was generated via the Localized Resource builder call.

Applying Localization to other Presentation Builders Lookup Table builders can be used to declare resource keys in such a way that they can be applied easily to UI elements such as select lists and radio buttons. Resource keys can be defined in XML in a Lookup Table builder call. This Lookup Table can then be referenced by the UI element builder. As long as there are matching resource key names and translated values in the Resource Bundle, the list of choices in the UI element will get localized. Lookup Table builder calls can be added directly to the model or they can

be declared in Rich Data Definition (RDD) files. By declaring them in RDD files, these Lookup Table builder calls can be reused easily by many portlets. Rich Data Definition builder calls can also be used to apply localization to presentation builders. An RDD builder call is associated with a particular schema in the model. The UI element definitions in the base RDD file referenced in this builder call become available as choices for each element in the schema. The base RDD file must have a reference to a Resource Bundle so that the resource keys defined in the base RDD file can get translated via localization.

Sample description There are two models in this sample: multi_language_orders_1 and multi_language_orders_2. They are very similar in design. The only differences are that multi_language_orders_2 has a Rich Data Definition (RDD) builder call and a Portlet Adapter builder call. The RDD provides a more sophisticated UI using Lookup Table builders and resource keys for translation. The Portlet Adapter builder call enables a Help page that is translated into French and English. By using the portlet’s Help page while logged in as a test user with French as the preferred language, it is easy to demonstrate translation of entire pages.

Resource Bundles There are two Resource Bundles in this sample. The first one contains the English versions of the resource keys for the View & Form column and field labels and the Page Automation buttons. It also contains the translations for the named <span> tags that provide placeholders for the paragraph at the top of the page, the link to the help page, and the table heading. The second one contains the resource keys referenced by the various base definitions found in the Base Data Definition referenced in the RDD builder call found in multi_language_orders_2. Both of these files and their French translations are found in the work/source/com/bowstreet/samples/multi_language folder. Their file names are multi_language_orders.properties and multi_language_data_def.properties respectively. Note: It would have been acceptable to merge these two files into a single file, but separating them makes it easier to understand which resource keys go with which localization features. When working with multi_language_orders_1, you should open both the default and the French versions of multi_language_orders.properties. By flipping back and forth between these two files, you will be able to see their translations easily. You will also see that this model does not translate any data or choices in any fields. Instead, only static text such as the paragraph at the top of the summary page, the help link, and all field and column labels are translated. This file is referenced by the Localized Resource builder call in both models. When working with multi_language_orders_2, you will see that the data in the summary page and detail pages are translated. You will also see a more sophisticated UI on the edit page. These additional translations are implemented through an RDD builder call that references a cleverly designed Base Data Definition file. This file references the

second resource bundle, multi_language_data_def.properties, which provides translations for the choices in the select lists and for data in the summary and detail pages. This Resource Bundle also contains the resource keys for the Calendar Picker widgets that are applied to the date fields.

Rich Data Definition In the second model, there is a Rich Data Definition builder call. In the Base Data Definition input, this builder call references a Base Data Definition file called /WEBINF/samples/multi_language/data_definitions/base_definition.xml. This file contains the definitions referenced in the Data Definition Editor section of the RDD builder call. Each schema field represented in the Data Definition Editor section can be assigned UI features and behaviors that are defined in the Base Data Definition file. For example, the STATUS field has a base definition of base_Status. If you open the Base Data Definition file and examine the definition named base_Status, you will see that it contains an element named LookupTable. This definition effectively adds a Lookup Table builder to the model although this builder does not appear in the builder call list. It can be used, however, by other builder calls that reference Lookup Table builders in exactly the same manner as if it were in the builder call list. Another important part of the base_Status definition is that the Lookup Table contains value-name pairs that include references to resource keys. These references make it possible for UI elements such as select lists, radio buttons, and checkboxes to present locale-specific choices. In order to localize these choices, the resource_key attribute values of the name elements must match resource keys in a Resource Bundle. If you look at the very top of the Base Data Definition file, you will see a reference to the Resource Bundle. This file is the second Resource Bundle described above: multi_language_data_def.properties. Other definitions in this file are used for formatting dates. By examining those definitions, it should be clear how they work. In order to see the locale-specific date-time formats, you will have to open the various translated Resource Bundle files. Table 1. Sample package contents Filename and location samples/multi_language/ orders_view_and_form_view.htm samples/multi_language/ multi_language_ordersHelp.html

samples/multi_language/en/ multi_language_ordersHelp.html samples/multi_language/fr/

Description Base layout page for View & Form in both models. The default portlet help / help link page that appears when a language other than English or French designated as the user’s language preference. The English version of the portlet help / help link page. The French version of the portlet

multi_language_ordersHelp.html samples/multi_language/styles/ multi_language.css samples/multi_language/styles/ multi_language_help.css WEB-INF/models/samples/multi_language/ multi_language_orders_1.model WEB-INF/models/samples/multi_language/ multi_language_orders_2.model WEB-INF/samples/multi_language/ data_definitions/ base_definition.xml

WEB-INF/work/source/com/bowstreet/ samples/multi_language/ multi_language_orders.properties

WEB-INF/work/source/com/bowstreet/ samples/multi_language/ multi_language_orders_fr.properties

WEB-INF/work/source/com/bowstreet/ samples/multi_language/ multi_language_data_def.properties

WEB-INF/work/source/com/bowstreet/ samples/multi_language/ multi_language_data_def_fr.properties

help / help link page. The style sheet used by the base layout pages in the View & Form builder calls in both models. The style sheet used by the portlet help / help link pages. Model used to demonstrate localization basics. Model used to demonstrate using RDD and portlet help files with localization. The base RDD file containing predefined UI types that use Lookup Table builders and localization date formatting. The default language version of the Resource Bundle referenced by the Localized Resource builder and the View & Form builder in both models. The default language is English. The French language version of the Resource Bundle referenced by the Localized Resource builder and the View & Form builder in both models. The default language version of the Resource Bundle file referenced by the RDD builder in the second model. The default language is English. The French language version of the Resource Bundle file referenced by the RDD builder in the second model.

Figure 1. This screen capture shows Model 1 running summary page in English

Figure 2. This screen capture shows Model 1 running summary page in French

Figure 3. This screen capture shows Model 2 running summary page in French

Instructions for running the sample To run the sample application: 1. Download the sample ZIP file and import it into a project using the File, Import, WebSphere Portlet Factory Archive command. The project must have the Tutorials and Samples / Applications feature set installed. 2. Rebuild the portlet WARs to deploy the portlets added to the project in the last step. a. Right-click the project name. b. Choose Rebuild WAR > Rebuild Portlet WARs. 3. Test the first model a. Open the model in the WEB-INF/models/samples/multi_language folder called multi_language_orders_1.model. This model uses the Orders service to display summary and detail data about orders and allows updating of orders data. b. Run this model to ensure it works. c. Click the Help Link to view the Help page in English. d. Take a few moments to become familiar with it by opening and editing a record. 4. Setup the browser to use multiple languages – assuming Internet Explorer a. From the Tools menu, choose Tools > Internet Options b. Click the Languages… button. c. In the Language Preference dialog box, click Add…

5.

6.

7.

8.

d. Select French(France)[fr] and click OK. e. Use the Move Up button to put French at the top of the list. Click OK then click OK again to save these changes. f. Close the browser so that the next time it is used, French will be the default language. Run the model again. Much of the page should be in French now. a. On the summary page, the paragraph at the top, the link to the Help page, and the column headings should be in French. b. Click the Aide Link to view the Help page in French. c. On the detail and edit pages, the field labels and navigation buttons should also be in French. d. None of the data should be translated yet. You will see how that is done in the second model. Compare and contrast the English and French versions a. Set the web browser language preference back to English and close the browser. b. Run the same model again. This time, everything should be in English. c. Feel free to switch back and forth between the English and French versions until you are comfortable with how it all works. d. Switch back to Portlet Factory Designer when finished experimenting with this model in the browser. In Designer, open the model called multi_language_orders_2.model. a. Run this model. It is very similar to the previous one, but the UI is slightly different on the edit pages because this model has a Rich Data Definition (RDD) builder call that applies base definitions for select lists and date fields. These definitions are in the Base Data Definition file referenced in the RDD builder call. b. On the summary page and detail, you should see the same French translations for the static text as in the first model plus translations of the data. On the edit pages, you should see select lists and calendar pickers translated into French. c. Feel free to switch back and forth between the English and French versions until you are comfortable with how it all works. Test this portlet in WebSphere Portal a. Change the preferred browser language to English. b. Login into Portal as an administrator. c. Create a page or navigate to an existing page and add this portlet. Its name is Sample Multi Language Orders. d. Create a user in Portal whose language preference is French. This user will also need access to this portlet and to the page containing it. e. Log out and log in as the French user. f. The portlet should be in French. Test the portlet by opening and editing a record. It should behave as it did when you tested it running in a browser. g. The Aide Link at the top of the page will be disabled. The portlet’s help page, accessible via the Aide link on the portlet’s menu in the upper right

corner of the portlet’s border should be active. Choose Aide from this menu and you should see the French version of the help page.

Additional considerations Resources WebSphere Portlet Factory product documentation http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/proddoc.html

WebSphere Portlet Factory support http://www.ibm.com/software/genservers/portletfactory/support/ developerWorks forums http://www.ibm.com/developerworks/forums/wsdd_forums.jsp Trademarks • DB2, IBM, Lotus, Tivoli, Rational, and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both. • Windows and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, or both. • Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. • Other company, product, and service names may be trademarks or service marks of others.