+

Search Tips   |   Advanced Search

Language support

Overview

Portal can serve portal views in a user's preferred language.

Some back-level versions of browsers used might have difficulty representing specific languages, depending on the defined character set. To fix, define the same preferred language for the browser and the portal it accesses.

WebSphere Portal has already been translated into a number of languages.

The names for directories containing language-dependent resources follow the ISO 639 naming convention.


Support a new language

To support a new language add resource bundles and JSPs. Some JSPs use resource bundles; others, such as help JSPs, are translated directly. To update the list of available languages we use...

We can also xmlaccess to remove an existing language. The new language is then listed in the language selection menu boxex available in administration portlets, or for example, in Edit My Profile, Preferred language.

The new language will be available only to portlets that we add to the portal, if these portlets support the newly added language and if you make the required language files available. None of the WebSphere Portal user interface or messages will be translated to the new language.


Add resource bundles for a new language

Resource bundles are used to store text displayed in JSPs or text used in Java code. In WebSphere Portal, resource bundles are located in the JAR files wp.ui.jar and wp.theme.customizer.ext.jar in the nls directory inside the file.

The JAR file wp.ui.jar is located in:

The JAR file wp.theme.customizer.ext.jar is located in:

To add new resource bundles for additional languages, place them in:

The naming convention for resource bundles is [bundle]_[language]_[country]_[variant].properties . The ISO standard ISO-639 is used for the language codes of most languages. For Hebrew the old language code iw is used. The ISO standard ISO-3166 is used for the country/region codes. WebSphere Portal supports the use of [variant], although resource bundles supplied with the portal do not use it.

If the portal configuration includes Lotus Collaborative Services, add a new CSRes_language.properties file for each additional language to the following directory:

WebSphere Portal uses properties files called by the Java class java.util.ResourceBundle to store text rendered in JSPs. The Java mechanism searches for the resource bundles in the following order:

  1. [bundle]_[language]_[country]_[variant].properties
  2. [bundle]_[language]_[country].properties
  3. [bundle]_[language].properties
  4. [bundle].properties

In WebSphere Portal, the default bundles [bundle].properties are in English.

It is requires that all WebSphere Portal defined languages have resource bundles defined as well for the themes to function correctly. IBM recommends that after a language is installed, the resource bundles located within wp.ui.jar and wp.theme.customizer.ext.jar are processed through the procedure outlined later in this topic.

To add a resource bundle, proceed with the following steps:

  1. Copy all existing resource bundles into WP_PROFILE/PortalServer/config/nls directory.

  2. Name it according to the naming convention for resource bundles using locale code for the language(s) installed.

  3. Translate the resource bundle files.

  4. Convert it into Unicode with the Native-to-ASCII converter native2ascii which comes as part of JDK. For more detail on native2ascii see the Java documentation native2ascii - Native-to-ASCII Converter.

  5. Restart Portal so that the new resource bundles can be recognized.


Add JSPs for a new language

Some JSPs containing mostly text, such as help JSPs, are translated directly which means that the text is contained in the JSP and not in a resource bundle. For JSPs that do not use resource bundles, you need to copy and translate an existing JSP and store it in the appropriate location.

The location of JSPs can be, for example, jsp/[mime-type]/[language]/[country]/[variant]/files.jsp. For instance, existing help JSPs are already translated in WebSphere Portal and placed in the relevant [language]and [country] subdirectories. When deciding where to store new JSPs, you need to consider how the portal locates a JSP for rendering its content.

The following is an example of the order in which directories are searched, where path1 is a user-defined path, ie5 is the markup version (here: Internet Explorer 5), and the locale is en_US:

  1. /html/path1/ie5/en_US/mytemplate.jsp

  2. /html/path1/ie5/en/mytemplate.jsp

  3. /html/path1/ie5/mytemplate.jsp

  4. /html/path1/en_US/mytemplate.jsp

  5. /html/path1/en/mytemplate.jsp

  6. /html/path1/mytemplate.jsp

  7. /html/en_US/mytemplate.jsp

  8. /html/en/mytemplate.jsp

  9. /html/mytemplate.jsp

  10. /mytemplate.jsp

This means that if the user language is not supported, the portal will choose the file in the locale independent location, which in the example is the English file.


National language support for People Finder fields

All fields of the People Finder portlet must have associated language strings defined in each language property file, PeopleFinderUI_language_code.properties. The field names are the names of the corresponding attributes in Member Manager.

For each People Finder field, three strings are required:

Example:

The resource key for each field refers to the appropriate language property file, /nls/PeopleFinderUI_language_code.properties. Foreign language translations of People Finder fields must be stored in the appropriate language property file.

Language properties files are in the following location on the WebSphere Portal server (nnnnnnn represents a random number generated by the installation process when the lwppeoplefinder.jar file is installed):

PortalServer_root/people/people.impl/peoplefinder/portlet/nnnnnnn.ear/lwp_peoplefinder_war.ear/lwp.peoplefinder.jsr168.war/WEB-INF/lib


Parent: Language support
Related:
Set the language fallback filter
Related:
Dynamically changing the language during the session
Related reference:
Sample XML configuration files
XML samples for creating or removing language definitions
Related:
Change the character set for a language
Set the the language

native2ascii - Native-to-ASCII Converter


XML samples for creating or removing language definitions

We can modify these XML samples and use them to create or remove language definitions from the portal.

The following XML sample shows how we use xmlaccess.sh to create Japanese language in the portal: 

<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="update"
         xsi:noNamespaceSchemaLocation="PortalConfig_8.0.0.xsd">
     <portal action="locate">
          <language action="update" domain="rel" locale="ja">
          </language>
     </portal>
</request>
The following XML sample shows how we use xmlaccess.sh to remove Japanese language in the portal: 
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="update"  
         xsi:noNamespaceSchemaLocation="PortalConfig_8.0.0.xsd">
    <portal action="locate">
         <language action="delete" domain="rel" locale="ja">
         </language>
    </portal>
</request>


Parent: Support a new language


Change the character set for a language

The character set is stored in the database. This is the character set used for the response to the user. We can change the character set for a language.

To change the character set for a language, use the Supported Markups portlet. Proceed as follows:

  1. Click Administration > Portal settings > Supported markups.

  2. Select the markup for which to change the character set.

  3. Click Edit selected markup.

  4. Click Set locale-specific settings.

  5. Select the language for which to make the change.

  6. Click Edit setting for selected language.

  7. Change the character set for the selected language in the selected markup.

  8. Click OK to save the changes, or click Cancel to return without saving.

  9. Again, on the panel with the list of languages and on the panel for editing the markup, click OK to save your changes, or click Cancel to return without saving.
For details about how to perform these tasks refer to the Supported Markups portlet help.

For a portlet to be rendered correctly, the language of the portlet must be supported by the character set of the portal.

To help the user's browser to render content correctly, the used character set is written to the HTTP header of the response stream. The default encoding is UTF-8. If it set to another encoding, we can force the default encoding by setting the JVM parameter as follows default.client.encoding=UTF-8 .


Parent: Language support
Related:
Set the language fallback filter
Related:
Dynamically changing the language during the session
Related:
Support a new language
Set the the language


Dynamically changing the language during the session

Allow users to change the language during their session.

If you want the users to be able to change the language during the session, use the following command provided by IBM WebSphere Portal: 

<portal-navigation:url command="ChangeLanguage">
   <portal-navigation:urlParam name="locale" value="language"/>
</portal-navigation:url>

...where... language is the two character code for the required language, such as en, de, or fr. For a list of the available languages and their two character codes refer to Language support.

For users to be able to dynamically change the language for the session, add a link to the portal theme with the following text and link reference:

Users can then click this link to change to the language specified by the locale parameter with the command. To make more than one language available to users, you create a separate link for each language.

Example: To create links for English and German, add the lines shown in the following example to the banner area of the theme: 

<!-- add these lines -->
<a href="http://setgetweb.com/p/portal80/<portal-navigation:url command="ChangeLanguage"><portal-navigation:urlParam name="locale"       value="en"/></portal-navigation:url>">English</a>
<a href="http://setgetweb.com/p/portal80/<portal-navigation:url command="ChangeLanguage"><portal-navigation:urlParam name="locale"       value="de"/></portal-navigation:url>">Deutsch</a>

<%-- logout button --%>

The banner area can be defined in different files, depending on the different themes. Themes in recent portal versions commonly define the banner area within the Default.jsp, whereas older themes can include a separate JSP, such as banner_toolbar.jsp. For more information about locating the files for the themes refer to the topic about the Location of theme resources.


Parent: Language support
Related:
Set the language fallback filter
Related reference:
Location of theme resources
Related:
Support a new language
Change the character set for a language
Set the the language
Tags used by the portal JSPs


Select the language

We can control the multiple language-specific settings within the portal.


Change the default portal language

After the installation we can change the default language of the portal. To do this, use the Global Settings portlet. Select Administration, Portal settings, Global Settings. From the pull down list, select the required default language for the portal. This can be, for example, en for English. For a list of languages supported by the portal refer to the topic about Language support.

The Global Settings portlet does not work in portal cluster configurations. For portal clusters set the portal default language in the portal Localizer service using the WAS admin console. For details about how to set the language refer to the topic about Setting service configuration properties.


Portlets

A portlet can support one or more locales. All portlets must have their own default language specified in the deployment descriptors. Otherwise the portlet cannot be installed.


Change titles for pages

We can edit titles for pages in the portlet for Managing Pages using the configure option for the locale specific settings. Select Administration, Portal User Interface, Manage pages. Click the Edit Page Properties icon, expand the Advanced options, and select the option for setting page titles and descriptions. We can enter a different title for each available language.


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. If required, the user can later change the selected language in the self care portlet by selecting Edit My Profile. The selection list shown to the user for choosing a language shows all available portal languages.

The user's language selection does not become effective until after the user has logged in.


Language determined by the portal

The portal determines the language for rendering the portal content by a search process along the following sequence at login time:

  1. The language encoded in the URL takes highest priority. The portal does not encode a locale into the URL by default. However, we can add code to the JSPs to support dynamic language selection. For details about this refer to Dynamically changing the language during the session.

  2. If the user has logged in, the portal displays in the preferred language selected and stored in the user repository by the user.

  3. If no preferred user language can be found, the portal looks for the language defined in the user's browser. If the portal supporto that language, it displays the content is that language. If the browser has more than one language defined, the portal uses the first language in the list to display the content.

  4. If no browser language can be found, for example if the browser used does not send a language or if the portal does not support the language set in the browser, the portal resorts to its own default language.

  5. If the user has a portlet that does not support the languagthat was determined by the previous stepso that portlet is shown in its own default language.

This sequence 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 this sequence, it tries to find the resources in a similar language.

For example, if the determined language was US English (en_US), the next closest option is English (en).

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 default language of the portlet. This way, the portal can show individual portlets in different languages.

If a page does not support any of the languages determined by the steps given in the preceding list, then the navigation displays the object ID of the page rather than the page title. Such an object ID can be, for example, 7_0_5T .


Parent: Language support
Related:
Set the language fallback filter
Related:
Dynamically changing the language during the session
Related:
Support a new language
Change the character set for a language


Set the language fallback filter

We can set the language fallback servlet filter to perform fallback for the entries in the browser locale list. This changes the way by which the portal determines the language for rendering portlets.

By default portal v8.0 recognizes whether a general language code is secondary or farther down in the browser priority list and ignores all regional variations that do not directly match a language defined by the portal.

For example, if the browser locale list specifies "ja-JP", "de", "ja", the portal ignores the entry "ja-JP" and falls back to the second entry of "de", as it recognizes that "ja-JP" does not have a match among the portal defined locales and that the more generic version "ja" of this locale is further down in the list behind "de". This behavior conforms to the HTTP specification.

If you turn the filter on, the portal performs a fallback for all entries and removes duplicates of the fallback localethat appear later in the list. In the example browser locale list of "ja-JP", "de", "ja" as given before, the portal recognizes that "ja-JP" does not match any of the portal defined locales, but performs a fallback to the portal defined locale "ja". It uses "ja" as the locale of choice and ignores the 3rd entry "ja" from the list. The resulting locale list used by the portal is "ja", "de". This bypasses strict adherence to the HTTP specification of accepting and displaying languages and uses the fallback option instead. This also makes the WebSphere Portal v8.0 behave the same way as earlier portal versions.

You set this filter in web.xml . This file is located in the directory WP_PROFILE/config/cells/node-name/applications/wps.ear/deployments/wps/wps.war/WEB-INF. By default the portal is set to use the extended locale filter as follows: 

<filter>
   <filter-name>Locale Filter</filter-name>
   <filter-class>com.ibm.wps.engine.ExtendedLocaleFilter</filter-class>
</filter>
To switch to the language fallback servlet filter, replace the extended locale filter by the sorting locale filter as follows: 
<filter>
   <filter-name>Locale Filter</filter-name>
   <filter-class>com.ibm.wps.engine.SortingLocaleFilter</filter-class>
</filter>
After you set filters, restart the portal for the change to take effect.

Example: Assumthat the browser sends the Accept-Language header "DE_de, en". The user prefers German as spoken in Germany as first priority, then English, but not German in general. In a portal scenario, this would result in serving resources in "en", even though "de" would be supported (but is not acceptable according to the header). Using the ExtendedLocaleFilter adds all fallback locales to the header, preserving the relative order of the original locales in the header. The result would be "DE_de, en, de", with the fallback to "de" appearing after "en" to match the user preference.

In contrast, com.ibm.wps.engine.SortingLocaleFilter gives fallbacks precedence over the original order of locales in the header. For "DE_de, en" the filter would generate "DE_de, de, en", giving all fallbacks for "DE_de" the same relative priority as "DE_de".

We can write our own filters and apply our own locale fallback logic. WebSphere Portal uses the value of the Accept-Language header for further processing.