The Oracle Portal has a robust set of APIs for interacting with Oracle Portals 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

A provider can use the 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 then to retrieve the appropriate translation for the user.  The context APIs determine the users language environment using the users browser setting for language. When a requested translation does not exist the APIs will return the base language translation.

For example, if the providers register procedure is used to load US and French translations for the portlet title and when the portlet is being rendered the provider implementation retrieves the title string from the NLS table, then the following will be the result:

• A request for a French string will cause the title will appear in French.
• A request for a US string will cause the title will appear in US.
• A request for a Chinese string will cause the title will appear in US.

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.

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.

Revision History:

• November 21, 2000.