Level: Introductory Lex Sheehan (lsh33han@us.ibm.com), Senior Software Engineer, IBM
01 Apr 2003
© Copyright International Business Machines Corporation 2003. All rights
reserved.
Introduction
Natural Language Support (NLS) issues range from:
- Ability to translate application into multiple languages
- Ability to translate application into languages that use different character sets
- Applications' ability to support bi-directional text
- Applications' support to recognize multi-cultural issues
- Applications' ability to support international date and time formats
- Flexibility of the user interface with layout attributes
If your product is not NLS compliant, then the following users are affected:
- Users who read, write, and understand a language other than the original language that was used to develop the
application.
- Users who read, write, and understand a language that is a bi-directional language, such as Arabic. Or, a language
that does not use the same character, such as Japanese and Chinese.
- Users who have customs or values that are different than the original country where the application
was developed.
- Users that do not use the same date and time format that is customary to where the application
was developed.
This article provides NLS considerations and tips for WebSphere Portal 4.1.2 as follows:
- Supporting any format of a file in multilanguages
- Displaying text in different languages in the portlet code
- Displaying text in different languages in your JSPs
- Using NLS-related portal JSP tags
- Supporting text for bidirectional languages
- Displaying multilingual JSPs
- Using a language not on list of translated languages
- Changing company information
- Changing Portal help pages
NLS Support in WebSphere Portal Server
In WebSphere Portal Server, the entire system of page templates, themes, skins, and
portlet rendering is fully enabled for internationalization and accessibility for people with disabilities.
The Portal Server generates markup that complies with the American Disability Act (ADA) as defined in Section
508 of the Web Accessibility Standards and meets the guidelines of the W3C Web Accessibility Initiative.
To reach as many users as possible, Portal Server supports different languages for different locations. For instance,
a large international corporation may address users in different countries through multilingual Web sites. In this context,
the Portal can concurrently serve portal views to large numbers of users, each in the preferred language of the
individual user.
If necessary, the Portal can serve portal pages containing portlets that are shown in different languages. In the
case of portlets not supporting a desired language, the Portal tries to match the user's language preference. For
example, if a page for a Japanese user shows several portlets in Japanese and a portlet is added that supports English
only, then the page shows the new portlet in English and the other portlets in Japanese.
Note that some backlevel versions of browsers and browsers that are not in widespread use may have restrictions
in representing specific languages. This depends on the defined character set. To render the language correctly,
you need to define the preferred language for the browser as the language of the portal
that the browser accesses.
Portal Server has been translated into the following languages:
- English
- French
- German
- Italian
- Spanish
- Czech
- Hebrew
- Polish
- Turkish
- Brazilian Portuguese
- Japanese
- Korean
- Simplified Chinese
- Traditional Chinese
The next sections in this article provide tips that help you enable your WebSphere Portal 4.1 applications for NLS.
Supporting any format of file in multilanguages
Use the portlet context's getResourceAsStream().to open the file for the particular markup and human language.
- Package your multi-language (ML) files in the war file using the following structure:
- In your portlet code, call the portlet context's
getResouceAsStream() method as
follows:
InputStream dataIOS =
getPortletConfig().getContext().getResourceAsStream(" /WEB-INF/
jsp/data.file", htmlClient, chineseLocale);
|
The getResourceAsStream() method searches your directory
structure for the data.file that matches the markup, locale, and variant.
getResourceAsStream JavaDoc
public java.io.InputStream getResourceAsStream(java.lang.String path,
Client client,java.util.Locale locale)
|
Returns the resource located at the given path as an InputStream object.
The data in the InputStream is any type or length. The method returns null if no resource
exists at the given path.
To access protected resources, prefix the path with /WEB-INF/, such as
/WEB-INF/myportlet/myportlet.jsp. Otherwise, the direct path is used,
such as /myportlet/myportlet.jsp.
This method is enabled for multi-language and multi-device support.
For example, the /myportlet/mytemplate.jsp JSP file is searched for using the HTML browser
in the following order:
-
/myportlet/html/en_US/mytemplate.jsp
-
/myportlet/html/en/mytemplate.jsp
-
/myportlet/html/mytemplate.jsp
-
/myportlet/mytemplate.jsp
Displaying text in different languages in the portlet code
Use the portlet context's getText() method to display a text from a
file. The file must be in name-value pairs, such as a Properties formatted file.
- Package and name your multi-language files as follows in the par structure:
Files in the par structure
- The folder structure must be under the
/WEB-INF/classes directory.
- Name your files in the form of
data_nl.properties, where nl is the supported language.
In this example, we have two files, employee.properties and employee_de.properties.
- The contents of the properties file are:
where key appears in all the properties files, and value is in the corresponding language.
For example:
employee.properties
InitialTitle = Portlet showing employees with the specified Job
Label = Please select a Job title:
|
employee_ de. properties
InitialTitle = Portlet zeigt Mitarbeiter mit der ausgewählten Tätigkeit
Label = Bitte wählen Sie eine Tätigkeit aus:
|
- In your portlet code, access your text as follows:
String localizedText =
getConfig().getContext().getText("nls.data", "welcomeHeader",
getLocale());
|
The first argument in the getText() method is the dot delimited string of the
directory structure and filename. The second argument is the key that you
want to extract the value. The third argument is the locale object.
Displaying text in different languages in your JSPs
- Package your multilanguage properties file as in the case for the display ML text in Java code.
- In your JSP, display your text as follows:
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI %>
<wps:text bundle="properties_file" key="string">
|
Writes a localized string to the output stream. When no resource bundle is found, the content between the
start and end tag is written to the output stream.
Specifies the resource bundle. This parameter is required.
Specifies the key to be found in the resource bundle. This parameter is required.
In the following example, the value of the InitialTitle and Label parameters are
retrieved from the portlet's
employee.properties file.
<wps: text bundle="nls.employee" key=" InitialTitle"> Portlet showing employees
with the specified Job
</ wps: text>
<wps: text bundle="nls.employee" key=" Label"> Please select a Job title:
</ wps: text>
|
Using NLS-related portal JSP tags
This section describes the NLS-related tags used in the portal JSPs. The corresponding taglib file is named
engine.tld and is in the wp_root/app/wps.ear/wps.war/WEB-INF/tld
directory. You can use these tags to modify
the layout of the portal page. Note: These tags are not used by portlets.
For more information, see
Using
the Portlet API tags.
The portlet container provides tags for portlet JSPs. To make these tags available in a
JSP, the following directive is required at the beginning of the JSP:
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
|
Supporting text for bidirectional languages
Use the following tag to support text for bidirectional languages. Bidirectional languages are read
from right to left or from bottom to top. The attribute "is" is required.
The tag content is written only if the text is bidirectional:
The tag content is written only if the text is not bidirectional:
Locale tag attribute
<wps:if attribute="value">
|
Through the attributes of this tag, several conditions are checked. If the condition is true,
the content of the tag is written to the page. Otherwise, the content is skipped. More than one condition is
evaluated. For example, the locale must be en_US and the user must have selected the Home page in order for
the content of the following tag to be rendered:
<wps:if locale="en_US" screen="Home">
</wps:if>
|
Indicates whether the locale of the client is that of the specified locale (or subtype of the specified locale).
You can specify a comma to separate a list, such as en, en_US.
Indicates whether the locale of the client is not the specified locale (or subtype of the specified locale). You can
specify a comma to separate a list, such as en, en_US.
Text for a given key in the specified language
<wps:text key="key" bundle="bundle">
|
Returns the text for a given key in the specified language. The key indicates a parameter in a resource
bundle or properties file, indicated by bundle. Both attributes are required. For example, in Banner.jsp,
you can use this tag to generate the ALT text for the banner image.
<img alt='<wps:text key="title" bundle="nls.engine">
Portal Title
</wps:text>' src='<wps:urlFindInTheme file="logo.gif"/>'>
|
The value of the title parameter is found in the appropriate resource bundle. The value, nls.engine,
indicates a locale-specific properties file.
<wps:textParam key="key" bundle="bundle">
|
If the text that is retrieved contains placeholders in the form of "{0}", "{1}", "{2}", and so on, you
can set these using the title tag. Enter the content for this tag the text you want to substitute the
placeholders. You can use an expression. For example, the welcome parameter in a resource bundle is set as follows:
In the following example, the value of the <portletAPI:textParam> tag is written in place of the {0}.
<wps:text key="welcome" bundle="nls.engine">
<wps:textParam>World</portletAPI:textParam>
</wps:text>
|
In Banner.jsp, the <portletAPI:user> tag personalizes this greeting if the user is logged in. Notice
the punctuation outside of the second <portletAPI:textParam> tag.
<wps:if loggedIn="yes" screen="Home,LoggedIn">
<wps:text key="welcome" bundle="nls.engine">
Welcome <wps:textParam>
<wps:user attribute="givenName"/></wps:textParam>
<wps:textParam><wps:userattribute="familyName"/> </wps:textParam>!
</wps:text>
</wps:if>
|
NLS URL Link
Use this tag to create a URI that points to the caller of the portlet. You can pass a parameter or action in the URI
by including URIParameter or URIAction between the CreateReturnURI start and end tags.
The following example creates a URI to provide a link that returns the user to the portlet's previous mode or state.
<a href="<wps:CreateReturnURI/>">
<wps:text bundle="nls.my_portlet" key="back_label">
Back
</wps:text>
</a>
|
Displaying multilingual JSPs
There are cases when you want to have multilingual JSPs,
rather than using one JSP together with many different resource files.
For globally accessible portals, the portal server searches and selects the proper JSP pages based
on the target browser, and the target browser's settings for language and country. To enable a portlet
for language selection, its JSP files are packaged using the following directory structure:
jsp_path / markup_type / language / region / client / jspname.jsp
|
-
jsp_path is a path defined by the developer. For example, JSPs is located in the root of the WAR file
or in a JSP directory. However, this path must not include mime-type/language_region_variant.
The include() method already locates the correct JSP also in those directories.
-
markup_type is either html, wml, or chtml.
-
language is the language for this JSP; for example, en, ja, or de.
-
region is the country, region, or territory of the JSP; for example,
US, UK, or CA.
-
client is the type of device. For example, it can indicate a JSP with browser-specific markup,
such as Internet Explorere or Netscape 4.
During aggregation, the portal server searches for themes and skins starting with the most specific
subdirectory and moving up to the more general, higher-level directory. The portal server searches for the
JSP for a portal from the most specific to the least specific.
|
Location in the /themes directory
|
Location in the /skins directory
|
|---|
- /locale_country
- /locale
- /client
- /theme_name
- /markup
|
- /locale_country
- /locale
- /client
- /skins_name
- /markup
|
For example, let's take a request from a client using Internet Explorer Version 5 with
the locale set to en_US and the user's skins set to Shadow. The aggregation component of
the portal server searches for the Control.jsp file in the following order. When engineering
a site, you place files in the appropriate directory based on how you want the page to be served.
If the Control.jsp page has MS IE specific attributes, put that page in an "ie" directory.
-
/skins/html/Shadow/ie5/en_US/Control.jsp
-
/skins/html/Shadow/ie5/en/Control.jsp
-
/skins/html/Shadow/ie5/Control.jsp
-
/skins/html/Shadow/en_US/Control.jsp
-
/skins/html/Shadow/en/Control.jsp
-
/skins/html/Shadow/Control.jsp
-
/skins/html/ie5/en_US/Control.jsp
-
/skins/html/ie5/en/Control.jsp
-
/skins/html/ie5/Control.jsp
-
/skins/html/en_US/Control.jsp
-
/skins/html/en/Control.jsp
-
/skins/html/Control.jsp
-
/skins/Control.jsp
In this example, if the file is not found in the ../ie5/en_US directory,
the portal server looks for the file in the ../ie5/en directory. The portal server keeps moving
through this hierarchy until this file is found. If the file is required, it exists in the
/skins or /themes directory, with more specific versions of the file placed in
the appropriate subdirectory.
Using a language not on list of translated languages
This section describes how to select and change the language that is not on the list of translated languages.
It discusses:
- Installation
- Changing the default language
- Portlets
- Web services
- Changing titles and descriptions for pages
- Determining language selection by the user
- Determining language by the portal
- Changing the character set
Installation:
The installation panels for the portal installation use the language determined by the locale
of your system. For example, the operating system on the server on which the portal is installed. This language
is also stored in LocalizerService.properties after the installation as the default language for the portal.
Changing the default language:
To change the default language of the portal, set the locale.default.language, locale.default.country, and
locale.default.variant in LocalizerService.properties keys to your locale identifier.
For instance, to change
the default language to American English, specify en and US for the language
and country, respectively, for the first two parameters.
Portlets:
A portlet can support one or more locales. All portlets must have their own default language specified in
the deployment descriptor. Otherwise, you cannot install the portlet.
Web Services:
Remote portlets also need a default language. The portal server sends three languages to the remote server:
- The user language chosen during enrollment and self-care
- The language specified in the user's browser
- The portal default language
If none of the languages above is supported by the portlet, the portlet is shown in its default language.
Changing titles and descriptions for pages and places:
The portlet for working with places and pages allows you to change the titles of pages and places and
the descriptions of places. You can enter a different title and description for each available language.
You edit titles and descriptions for pages and places with the portlet for managing places and pages using
the Configure option.
Determining language selection by the user:
The user can select the preferred language for rendering portal content during the enrollment process.
The user can select from a list of available languages. The user can later change the selected
language in the self care portlet by selecting Edit my profile, then
Change personal information. The selection
list shown to the user for choosing a language corresponds to the languages in the
lib\app\config\language.properties file.
Note that the language selection of the user does not become effective until after the user has logged in.
Determining language by the portal:
The portal determines the language for rendering the portal content by a search process using the
following sequence at login time:
- If the user has logged in, the portal displays the preferred language selected by the user.
- If no user language is found, the portal looks for the language defined in the user's browser and
displays the content in that language.
- If no browser language is found, for example, if the browser does not send a language, the portal
resorts to its own default language.
- If the user has a portlet that does not support any of the three languages above, that portlet
is shown in its own default language.
The sequence listed above describes the language selection process that is applied for each user at
logon time. For pages viewed by anonymous users, only the last three steps for determining the
language apply. This applies, for example, before login and after log off.
The language determined by this selection process is applied to the complete portal. If the portal
or one component does not find the appropriate resources for the language as selected by the sequence
described above, it tries to find the resources in a similar language. For example, if the determined
language is US English (en_US), the next closest option is English (en).
The language is determined as follows:
- Resource bundles by the file name in the sequence
- JSPs by the hierarchy of the directory structure
This search sequence applies to all portal components individually down to portlets. For example,
if a portlet does not support the language selected by the portal, it is shown in the default
language of the portlet. This way, the portal may show individual portlets in different languages.
Changing the character set for a language:
The character set is stored in the database. This is the character set that is used for the
response to the user.
To change the character set for a language, use the Manage markups portlet.
- Select Portal administration -> Portal settings -> Manage markups.
- Select the markup for which you want to change the character set.
- Select Edit selected markup -> Set locale-specific setting.
- Select the language you want to make the change, then Edit setting for selected language.
- You can change the character set for the selected language in the selected markup.
Note that for a portlet to render correctly, the language of the portlet must be supported
by the character set of the portal.
The default encoding is UTF-8. To help the user's browser to render the content correctly,
the used character set is written to the HTTP header of the response stream.
The values in use are:
Japanese ja = Shift-JIS
Simplified Chinese zh = GBK
Traditional Chinese zh_TW, HTML = Big5
Traditional Chinese zh_TW, WML = UTF-8
Korean ko = KSC5601
All others = UTF-8
|
Changing company information
The text displayed in the banner of the portal page is defined in the
engine.properties file in the ../AppServer/lib/app/nls directory.
For multilingual sites, the file can have a language suffix corresponding to the locale,
for example, engine_es.properties for Spanish.
If WebSphere Portal cannot determine the client locale, the banner text is defined in engine.properties.
Use the following steps to change the banner text for each language supported by your portal site:
- Edit the
engine.properties file.
- Change the title parameter to the name that you want displayed in the portal banner.
- Save and close
engine.properties.
- Restart the application server for WebSphere Portal.
The License Agreement and Privacy Policy files contain information that you need to change
to include the relevant content specific to your company. These files are license.html and
privacy.html, respectively. You can find them in the wp_root/app/wps.ear/wps.war/html directory.
Changing Portal help pages
WebSphere Portal provides help information for the portal. You can customize this help page to reflect
the content and information about your organization's site. The portal help is a collection of HTML and
image files. The help pages include information about administering the portal. This information is
accessed from the Help link in the Portal navigation bar.
To prevent access to administrative information,
you can change the link to access another set of help files or remove links in the files provided.
To change the help link, edit the link in the JSPs provided for each theme that you use.
To make changes to existing help files, find the files in the following path,
wp_root/app/wps.ear/wps.war/doc/locale/InfoCenter/help,
where wp_root is the WebSphere Portal root directory and locale indicates the language.
The main portal help file is help_index.html in the
wp_root/app/wps.ear/wps.war/doc/locale/InfoCenter directory.
That file sets the frames for the banner, navigation, and help content.
As you add new help content, you need to update navText.txt and htmltoc.html
with links to the new files.
The original help is available in multiple languages. If your users require support for multiple languages,
you need to translate any new files that you create. Create a backup a copy of the original help
before you make changes.
Conclusion
This article provided tips and considerations to help you enable your WebSphere Portal Server 4.1 applications for
NLS. One of the most difficult part of programming a WebSphere Portal solution is discovering how to use the
hidden treasures that you get for free with the Portal Server framework. By using the tips in this article,
you can easily add NLS gems to your portal applications.
Related Information
Top of page
About the author
|
Lex Sheehan is a Senior Software Engineer with eBusiness Integration, Enterprise Application Development.
You can reach him at lsh33han@us.ibm.com.
|
About the author  | | | Lex Sheehan is a Senior Software Engineer with eBusiness Integration, Enterprise Application Development. You can reach him at lsh33han@us.ibm.com. |
Rate this page
| 
