2 Developing Locale Awareness

This chapter contains the following topics:

Developing Locale Awareness in Global Internet Applications
Locale Awareness in J2EE and Internet Applications
Locale Awareness in Oracle Application Server Component Applications

Developing Locale Awareness in Global Internet Applications

Global Internet applications need to be aware of the user’s locale.

Locale-sensitive functions, such as date formatting, are built into programming environments such as C/C++, Java, and PL/SQL. Applications can use locale-sensitive functions to format the HTML pages according to the cultural conventions of the user’s locale.

Different programming environments represent locales in different ways. For example, the French (Canada) locale is represented as follows:

Environment	Representation	Locale	Explanation
Various	ISO standard	`fr-CA`	`fr` is the language code defined in the ISO 639 standard. `CA` is the country code defined in the ISO 3166 standard.
Java	Java locale object	`fr_CA`	Java uses the ISO language and country code.
C/C++	POSIX locale name	`fr_CA` on Sun Solaris	POSIX locale names may include a character set that overrides the default character set. For example, the de.ISO8859-15 locale is used to support the Euro symbol.
PL/SQL and SQL	`NLS_LANGUAGE` and `NLS_TERRITORY` parameters	`NLS_LANGUAGE="CANADIAN FRENCH"` `NLS_TERRITORY="CANADA"`	See Also: Chapter 5, "Configuring the NLS_LANG Parameter"

Table 2-1 shows how different programming environments represent some commonly used locales.

Table 2-1 Locale Representations in Different Programming Environments

Locale	ISO	Java	POSIX Solaris	NLS_LANGUAGE, NLS_TERRITORY
Arabic (U.A.E.)	ar	ar	ar	ARABIC, UNITED ARAB EMIRATES
Germany (German)	de-DE	de_DE	de	GERMANY, GERMAN
English (U.S.A)	en	en_US	en_US	AMERICAN, AMERICA
English (United Kingdom)	en-GB	en_GB	en_UK	ENGLISH, UNITED KINGDOM
Greek	el	el	el	GREEK, GREECE
Spanish (Spain)	es-ES	es_ES	es	SPANISH, SPAIN
French (France)	fr	fr_FR	fr	FRENCH, FRANCE
French (Canada)	fr-CA	fr_CA	fr_CA	CANADIAN FRENCH, CANADA
Hebrew	he	he	he	HEBREW, ISRAEL
Italian (Italy)	it	it	it	ITALIAN, ITALY
Japanese	ja-JP	ja_JP	ja_JP	JAPANESE, JAPAN
Korean	ko-KR	ko_KR	ko_KR	KOREAN, KOREA
Portuguese (Portugal)	pt	pt	pt	PORTUGUESE, PORTUGAL
Portuguese (Brazil)	pt-BR	pt_BR	pt_BR	BRAZILIAN PORTUGUESE, BRAZIL
Turkish	tr	tr	tr	TURKISH, TURKEY
Thai	th	th	th	THAI, THAILAND
Chinese (Taiwan)	zh-TW	zh_TW	zh_TW	TRADITIONAL CHINESE, TAIWAN
Chinese (P.R.C)	zh-CN	zh_CN	zh_CN	SIMPLIFIED CHINESE, CHINA

If you write applications for more than one programming environment, then locales must be synchronized between environments. For example, Java applications that call PL/SQL procedures should map the Java locales to the corresponding NLS_LANGUAGE and NLS_TERRITORY values and change the parameter values to match the user’s locale before calling the PL/SQL procedures.

There are two thing that affect an application’s overall locale awareness: the development environment in which you create the application, and the target architecture for which the application is built. This chapter addresses these topics with respect to both monolingual and multilingual application architectures.

Determining a User’s Locale in Monolingual Internet Applications

A monolingual application, by definition, serves users with the same locale. A user’s locale is fixed in a monolingual application and is the same as the default runtime locale of the programming environment.

In almost all programming environments, almost all locale-sensitive functions implicitly use the default runtime locale to perform their tasks. Monolingual applications can rely on this behavior when calling these functions.

Determining a User’s Locale in Multilingual Internet Applications

In a multilingual application, the user’s locale may vary. Multilingual applications should do the following:

Dynamically detect the user’s locale
Construct HTML content in the language of the locale
Use the cultural conventions implied by the locale

Multilingual applications can determine a user’s locale dynamically in the following ways:

Based on the user profile information from an LDAP directory server such as Oracle Internet Directory (OID)

The application can store the user profile in the OID server provided by Oracle Application Server. The LDAP schema for the user profile should include a preferred locale attribute. This method does not work if a user has not logged on before.
Based on the default ISO locale of the user’s browser

Every HTTP request sends the default ISO locale of the browser with the Accept-Language HTTP header. If the Accept-Language header is NULL, then the locale should default to English. The drawback of this approach is that the Accept-Language header may not be a reliable source of information about the user’s locale.
Based on user input

Users can select a locale from a list or a group of icons such as flags.

You can use these methods of determining the user’s locale together or separately. After the application determines the locale, the locale should be:

Mapped to the locale representations that correspond to the programming environments on which the application runs
Used in locale-sensitive functions

See Also:
Table 2-1 for common locale representations in different programming environments

Locale Awareness in J2EE and Internet Applications

This section discusses locale awareness in terms of the particular programming language and development environment in which an application is written.

Locale Awareness in Java Applications

A Java locale object represents the corresponding user’s locale in Java. The Java encoding used for the locale is required to properly convert Java strings to byte data and vice versa.

Consider the Java encoding for the locale when you make the Java code aware of a user’s locale. There are two ways to make a Java method sensitive to the Java locale and the Java encoding:

Using the default Java locale and default Java encoding for the method
Explicitly specifying the Java locale and Java encoding for the method

Locale Awareness in Monolingual Java Applications

Monolingual applications should run implicitly with the default Java locale and default Java encoding so that the applications can be configured easily for a different locale. For example, to create a date formatter using the default Java locale, use the following method call:

DateFormat df = DateFormat.getDateTimeInstance(DateFormat.FULL, DateFormat.FULL);
dateString = df.format(date); /* Format a date */

Locale Awareness in Multilingual Java Applications

You should develop multilingual applications such that they are independent of fixed default locales or encodings. Explicitly specify the Java locale and Java encoding that correspond to the current user’s locale. For example, specify the Java locale object that corresponds to the user’s locale, identified by user_locale, in the getDateTimeInstance() method:

DateFormat df = DateFormat.getDateTimeInstance(DateFormat.FULL, DateFormat.FULL, user_locale);
dateString = df.format(date); /* Format a date */

Note that the only difference between the example code for the monolingual application and the multilingual application is the inclusion of user_locale.

Similarly, do not use encoding-sensitive methods that assume the default Java encoding. For example, you should not use the String.getBytes() method in a multilingual application because it is encoding-sensitive. Instead, use the method that accepts encoding as an argument, which is String.getBytes(String encoding). Be sure to specify the encoding used for the user’s locale.

Do not use the Locale.setDefault() method to change the default locale for these reasons:

It changes the Java default locale for all threads and makes your applications unsafe to threads
It does not affect the Java default encoding

Locale Awareness in Perl and C/C++ Applications

Perl and C/C++ use the POSIX locale model for internationalized applications.

Locale Awareness in Monolingual Perl and C/C++ Applications

Monolingual applications should be sensitive to the default POSIX locale, which is configured by changing the value of the LC_ALL environment variable or changing the operating system locale from the Control Panel in Windows.

See Also:

Table 2-1 for a list of commonly used POSIX locales

To run on the default POSIX locale, the applications should call the setlocale() function to set the default locale to the one defined by LC_ALL and use the POSIX locale-sensitive functions such as strftime() thereafter. Note that the setlocale() function affects the current process and all the threads associated with it, so any multithread application should assume the same POSIX locale in each thread. The following example gets the current time in the format specific to the default locale in Perl:

use locale;
use POSIX qw (locale_h);
...
$old_locale = setlocale( LC_ALL, "" );
$dateString = POSIX::strftime( "%c", localtime());
...

Locale Awareness in Multilingual Perl and C/C++ Applications

Multilingual applications should be sensitive to dynamically determined locales. Call the setlocale() function to initialize the locale before calling locale-sensitive functions. For example, the following C code gets the local time in the format of the user locale identified by user_locale:

#include <locale.h>
#include <time.h>
    ...
    const char *user_locale = "fr";
    time_t ltime;
    struct tm *thetime;
    unsigned char dateString[100];
    ...
    setlocale(LC_ALL, user_locale);
    time (&ltime);
    thetime = gmtime(&ltime);
    strftime((char *)dateString, 100, "%c", (const struct tm *)thetime));
    ...

You must map user locales to POSIX locale names for applications to initialize the correct locale dynamically in C/C++ and Perl. The POSIX locales depend on the operating system.

Locale Awareness in SQL and PL/SQL Applications

PL/SQL procedures run in the context of a database session whose locale is initialized by the NLS_LANG parameter in the database access descriptor (DAD). The NLS_LANG parameter specifies top-level NLS parameters, NLS_LANGUAGE and NLS_TERRITORY, for the database session. Other NLS parameters, such as NLS_SORT and NLS_DATE_LANGUAGE, inherit their values from these top-level parameters. These NLS parameters define the locale of a database session.

See Also:

Chapter 5, "Configuring the NLS_LANG Parameter"
Oracle9i Database Reference in the Oracle Database Documentation Library
Oracle9i Globalization Support Guide in the Oracle Database Documentation Library

for more information about NLS parameters

There are two ways to make SQL and PL/SQL functions locale sensitive:

Basing the locale on the NLS parameters of the current database session
Explicitly specifying the NLS parameters

Locale Awareness in Monolingual SQL and PL/SQL Applications

Generally speaking, the initial values of the NLS parameters inherited from NLS_LANG are sufficient for monolingual PL/SQL procedures. For example, the following PL/SQL code calls the TO_CHAR() function to get the formatted date, which uses the current values of the NLS_DATE_FORMAT and NLS_DATE_LANGUAGE parameters:

mydate date;
dateString varchar2(100);
...
select sysdate into mydate from dual;
dateString = TO_CHAR(mydate);

If the initial values of the NLS parameters are not appropriate, then use an ALTER SESSION statement to overwrite them for the current database session. You can use the ALTER SESSION statement with the DBMS_SQL package. For example:

cur integer;
status integer;
...
cur := dbms_sql.open_cursor;
dbms_sql.parse(cur, 'alter session set nls_date_format = "Day Month, YYYY"',
       dbms_sql.native);
status := dbms_sql.execute(cur);

Locale Awareness in Multilingual SQL and PL/SQL Applications

Multilingual applications should use ALTER SESSION statements to change the locale of the database session to the user’s locale before calling any locale-sensitive SQL or PL/SQL functions. You can use the ALTER SESSION statement with the DBMS_SQL package. For example:

cur integer;
status integer;
...
cur := dbms_sql.open_cursor;
dbms_sql.parse(cur, 'alter session set nls_language = "NLS_LANGUAGE_of_user_
       locale"', dbms_sql.native);
dbms_sql.parse(cur, 'alter session set nls_territory = "NLS_TERRITORY_of_
       user_locale"’, dbms_sql.native);
status := dbms_sql.execute(cur);

Alternatively, applications can specify the NLS parameters in every SQL function that accepts an NLS parameter as an argument. For example, the following PL/SQL code gets a date string based on the language of the user’s locale:

mydate date;
dateString varchar2(100);
...
select sysdate into mydate from dual;
dateString TO_CHAR(mydate, 'DD-MON-YYYY HH24:MI:SSxFF', 
                    'NLS_DATE_LANGUAGE=language' );
...

language specifies the Oracle language name for the user’s locale.

Locale Awareness in Oracle Application Server Component Applications

This section discusses locale awareness in terms of application development for particular Oracle Application Server components.

Locale Awareness in Oracle Application Server Wireless Services

Oracle Application Server Wireless sends all of the Mobile Context information as HTTP headers when invoking a request. The user locale is sent using the X-Oracle-User.Locale header. The locale value contains the ISO language, and an optional ISO country code, separated by a hyphen. For example, "en-US", "zh-CN", and "ja" are all valid locale values for this header. Mobile service applications should use the user locale specified in this header to determine the language and cultural conventions used in the user interface.

For example, JSP applications may retrieve the user locale as follows:

<%

   String userLocale = request.getHeader("X-Oracle-User.Locale");

%>

Locale Awareness in Oracle Application Server Forms Services

The Oracle Application Server Forms Services architecture includes:

A Java Client (browser)
Oracle Application Server Forms Services (middle tier)
The Oracle9i customer database (back end)

The Java Client is dynamically downloaded from Oracle Application Server when a user runs a Forms Services session. The Java Client provides the user interface for the Forms Services Runtime Engine. It also handles user interaction and visual feedback for actions such as navigating between items or checking a checkbox.

Oracle Application Server Forms Services consists of the Forms Services Runtime Engine and the Forms Listener Servlet. The Forms Services Runtime Engine is the process that maintains a connection to the database on behalf of the Java Client. The Forms Listener Servlet acts as a broker, taking connection requests from the Java Client processes and initiating a Forms Services runtime process on their behalf.

The NLS_LANG parameter for Forms Services initializes the locale of Oracle Application Server Forms Services. The NLS_LANGUAGE parameter derives its value from NLS_LANG and determines the language of Forms messages. The NLS_TERRITORY parameter also derives its value from NLS_LANG and determines conventions such as date and currency formats.

By default, the NLS_LANG parameter for Oracle Application Server Forms Services initializes the Java Client locale. The locale of the Java Client determines such things as button labels on default messages and parts of strings in menus.

See Also:

Oracle Application Server Forms Services Deployment Guide

Locale Awareness in Monolingual Oracle Application Server Forms Services Applications

A user’s locale is fixed in a monolingual Oracle Application Server Forms Services application and is usually the same as the default Forms Services locale. When you develop a monolingual Forms Services application, you must develop it to conform to the intended user’s locale. The database character set should be a superset of the Forms Services character set.

For example, a monolingual Forms Services application for a Japanese locale should include Japanese text, Japanese button labels, and Japanese menus. The application should also connect to a database whose character set is JA16SJIS, JA16EUC, or UTF8.

The NLS_LANG parameter in the default.env file controls the Forms Services locale. Additionally, in order to pass non-Latin-1 parameters to Forms Services, you can set the defaultcharset parameter in formsweb.cfg.

Locale Awareness in Multilingual Oracle Application Server Forms Services Applications

In a multilingual environment, the application can dynamically determine the locale of Oracle Application Server Forms Services in two ways:

Based on the user’s profile
Based on the user’s input

When you develop a Forms Services application you must choose one of these methods.

You can configure multilingual Forms Services applications by using multiple environment configuration files (EnvFile). For example, you can create a form called form.fmx and translate it into Japanese and into Arabic using Oracle9i Translator. Then save them as d:\form\ja\form.fmx (Japanese) and d:\form\ar\form.fmx (Arabic). Finally, create two environment configurations files, ja.env and ar.env, and specify the following in the appropriate environment file:

Form	Environment File	NLS_LANG	FORMS90_PATH
`d:\form\ja\form.fmx`	`ja.env`	`JAPANESE_JAPAN.JA16SJIS`	`d:\form\ja`
`d:\form\ar\form.fmx`	`ar.env`	`ARABIC_EGYPT.ARMSWIN1256`	`d:\form\ar`

Also, you can configure Forms Services to read the preferred language settings of the browser. For example, if you have a human resources application translated into 24 languages, then add an application entry in the formsweb.cfg file like the following:

[HR]
default.env
[HR.DE]
DE.env
[HR.FR]
FR.env
.
.
.

When the Forms Servlet detects a language preference in the browser, it checks the formsweb.cfg file to see if there is a translated version of the application.

For example, suppose the request is http://myserver.mydomain/servlet/f90servlet?config=HR and the preferred languages are set to German (DE), Italian (IT), and French (FR), in this order, then this is the order of priority. The Forms Servlet tries to read from the application definitions in the following order:

HR.DE
HR.IT
HR.FR
HR

If the Forms Servlet cannot find any of those configurations, then it uses the HR configuration (default.env).

This means that you can configure Forms to support multiple languages with one URL. Each application definition can have its own environment file that contains the NLS language parameter definition. You can also specify separate working directory information and path information for each application.

Additionally, Forms can display more than one language in a form if the Java client machine has the Albany WT J font installed. You can obtain this font from the utilities CD in your CD pack or from http://metalink.oracle.com.

The Albany WT J font should be copied to %WINDOWS%\Fonts if the client is using JInitiator 1.3.1, or %JAVA_HOME%\lib\fonts if the client is using Java Plug-in 1.4.1.

Locale Awareness in Oracle Application Server Reports Services

The Oracle Application Server Reports Services architecture includes:

A client tier (browser)
A Reports Server (middle tier)
An Oracle9i customer database (back end)

Oracle Application Server Reports Services can run multiple reports simultaneously upon users’ requests. The Reports Server enters requests for reports into a job queue and dispatches them to a dynamic, configurable number of pre-spawned runtime engines. The runtime engine connects to the database, retrieves data, and formats output for the client.

The NLS_LANG setting for the Reports Server initializes the locale of the runtime engine. The NLS_LANGUAGE parameter derives its value from the NLS_LANG parameter and determines the language of the Reports Server messages. The NLS_TERRITORY parameter derives its value from the NLS_LANG parameter and determines the date and currency formats. For example, if NLS_LANG is set to JAPANESE_JAPAN.JA16SJIS, then Reports Server messages are in Japanese and reports use the Japanese date format and currency symbol.

The dynamic environment switching feature enables one instance of the Reports Server to serve reports with any arbitrary environment setting, including NLS_LANG. Using the environment element in the Reports Server configuration file, you can create a language environment that can be referenced in two ways:

On a per-runtime engine basis through the engine element of the Reports Server configuration file
On a per-job basis using the ENVID command line argument

See Also:

Oracle Application Server Reports Services Publishing Reports to the Web for more information about dynamic environment switching

Report output is generated in the Reports Services character set. The client needs to be aware of the character set in which Reports Services generated the HTML or XML.

Locale Awareness in Monolingual Oracle Application Server Reports Services Applications

A user’s locale is fixed in a monolingual Oracle Application Server Reports Services application and is usually the same as the locale of the Reports Server. The database character set should be a superset of the Reports Server character set.

Locale Awareness in a Multilingual Oracle Application Server Reports Services Application

In a multilingual report, the application can dynamically determine the locale of the Reports Server in two ways:

Based on the user’s profile
Based on the user’s input

When you develop a report you must choose one of these methods.

You can use the dynamic environment switching feature to support multiple languages.

See Also:

Chapter 3, "Specifying the Page Encoding in HTML for Oracle Application Server Reports Services" for more information about the encoding of HTML, XML, and JSP report output
Chapter 5, "Configuring Oracle Application Server Reports Services for Global Deployment" for more information about specifying NLS_LANG parameters from the command line
Oracle Application Server Reports Services Publishing Reports to the Web for more information about dynamic environment switching

Locale Awareness in Oracle Application Server Discoverer

Oracle Application Server Discoverer can simultaneously support users with different locales. Discoverer always uses UTF-8 encoding for communication between the client and middle-tier services. Users may explicitly control the locale used for the user interface, or they may allow Oracle Application Server Discoverer to automatically determine a default. The order of precedence is:

Language and locale settings included in the URL for Oracle Application Server Discoverer
Language and locale settings specified in the Discoverer Connection (this is part of the Oracle Application Server Discoverer integration with Oracle Application Server Single Sign-On).
Language and locale setting specified in the user’s browser
Language and locale of Oracle Application Server

For example, suppose a user’s browser’s language and locale are set to German - Germany and the user goes to the URL to start Oracle Application Server Discoverer. The HTML page returned to the user is displayed in German. If the user clicks on the Discoverer Connection, which has the language and locale specified as English - US, the Discoverer user interface appears in English. This is because the Discoverer Connection settings take precedence over the browser’s settings.