Oracle9iAS Portal Developer Kit (PDK)
An Overview of National Language Support (NLS)

Introduction

The Oracle Portal has a robust set of APIs for interacting with Oracle Portal's NLS storage facility. This storage facility provides a mechanism for the storing and retrieving of strings in different languages. These APIs abstract the native Oracle NLS functionality and provide developers with a powerful storage mechanism for developing providers that support different language environments.

NLS services are available through the wwnls_api package.

Key Features

The Provider can use the NLS APIs to load the several translations for the strings displayed in their portlets. Once the strings have been loaded, the Provider can call the APIs to retrieve the strings from the NLS table as needed. The provider can then use Context APIs to retrieve the users language, and accordingly, retrieve the appropriate translation for the user. The Context APIs determine the users language environment using the users language setting in the browser. When a requested translation does not exist, the APIs will return the base language translation.

For example, let us assume that the provider's register procedure is used to load US and French translations for the portlet title. When the portlet is being rendered, the provider implementation retrieves the portlet title string from the NLS table and displays the following results:

• A request for a French string will cause the portlet title to appear in French.
• A request for a US string will cause the portlet title to appear in US English.
• A request for a Chinese string will cause the portlet title to appear in US English, as there is no translation available for the Chinese language.

Loading NLS Strings

NLS strings can be loaded in a script that is part of the provider installation. This script will essentially call the NLS add_string and set_string methods to create equivalent strings for different languages.

The Oracle Portal NLS APIs uniquely identify NLS strings using the combination of domain, sub-domain, and name. The domain and sub-domain provide a way to categorize NLS strings. The domain and sub-domain used by a provider should be unique enough to reasonable preclude conflicts with other users of the APIs.

Domain and sub-domain can be explained as follows.

• Domain : A particular area of the product. An example of a domain can be 'provider' or 'page-group'.
• Sub-domain : Sub-system of the domain. For eg, the sub-domain can be the provider name (Eg: 'HelloProvider') or the name of a sub-page (Eg: 'HelloPage').
  

It is also possible to set up NLS strings pertaining to the Provider, during the Provider Registration. While the user is on the 'Register Provider' screen in the UI, they can store NLS equivalents for strings such as the Provider display name. This would save the string for the browser setting of the language. It is then possible to change the browser language setting, and any new string that is entered will be marked for the new language setting in the NLS tables.

This functionality internally uses the NLS API for its purpose. This also illustrates how Portal administrators can use the NLS APIs to provide their users with a UI that stores NLS string equivalents.

When the registration method is used to load the strings, it is recommended that the provider's deregister procedure be used to remove string translations associated with their provider. The recommended method for loading and removing the NLS strings is the use of the provider's register and deregister procedures. This is recommended because the recommended use of the providers' register and deregister procedures are to perform the initialization and cleanup of the provider framework.

How to use NLS

The general model for working with the NLS service can be described as follows:

1. Load your NLS string definitions to the database using the string equivalents for each language you intend to use. For this purpose call the wwnls_api.add_string or wwnls_api.set_string with an appropriate domain, sub-domain, error message name and error text combination.
2. Retrieve the strings you require by using the wwnls_api.get_string API for the language that you desire.

For further details regarding implementation, refer to Implementing NLS Service.