Oracle Forms Developer and Reports Developer Release 6i:
Guidelines for Building Applications

A73073-01

PrevNext

Library

Solution Area

Contents

Index

4
Designing Multilingual Applications

This chapter explains how to design multilingual applications.

Section  Description 

Section 4.1, "National Language Support (NLS)" 

An overview of National Language Support and its components. 

Section 4.2, "Using National Language Support During Development" 

Instructions on developing applications using National Language Support. 

Section 4.3, "Translating Your Applications" 

Instructions on translating application elements not handled by NLS. 

4.1 National Language Support (NLS)

Oracle's National Language Support makes it possible to design multilingual applications. A multilingual application is an application which can be deployed in several different languages. Oracle supports most European, Middle Eastern, and Asian languages.

National Language Support makes it possible to:

4.1.1 The language environment variables

You can use the following parameters as language environment variables to specify language settings:

Parameter  Specifies 

NLS_CALENDAR 

the calendar system used. 

NLS_CREDIT 

the string used to indicate a positive monetary value. 

NLS_CURRENCY 

the local currency symbol. 

NLS_DATE_FORMAT 

the default format mask used for dates. 

NLS_DATE_LANGUAGE 

the default language used for dates. 

NLS_DEBIT 

the string used to indicate a negative monetary value. 

NLS_ISO_CURRENCY 

the ISO currency symbol. 

NLS_LANG 

the language settings used by Forms Developer and Reports Developer. 

DEVELOPER_NLS_LANG 

the language for the Builder. 

USER_NLS_LANG 

the language for the Runtime component. 

NLS_LIST_SEPARATOR 

the character used to separate items in a list. 

NLS_MONETARY_CHARACTERS 

the decimal character and thousands separator for monetary values. 

NLS_NUMERIC_CHARACTERS 

the decimal character and grouping separator for numeric values. 

NLS_SORT 

the type of sort used for character data. 

4.1.1.1 NLS_LANG

The NLS_LANG language environment variable specifies the language settings used by Forms Developer and Reports Developer.

NLS_LANG specifies:

The syntax for NLS_LANG is as follows:

NLS_LANG=language_territory.charset

language specifies the language and its conventions for displaying messages and day and month names. If language is not specified, the value defaults to American.

territory specifies the territory and its conventions for default date format, decimal character used for numbers, currency symbol, and calculation of week and day numbers. If territory is not specified, the value defaults to America.

charset specifies the character set in which data is displayed. This should be a character set that matches your language and platform. This argument also specifies the character set used for displaying messages.

For example, let's say you want your application to run in French. The application will be used in France. Data will be displayed using the WE8ISO8859P1 character set. You would set NLS_LANG as follows:

NLS_LANG=French_France.WE8ISO8859P1

Now let's say you want your application to run in French, but this time the application will be used in Switzerland. You would set NLS_LANG as follows:

NLS_LANG=French_Switzerland.WE8ISO8859P1

Note: You are strongly advised to set the language and territory parameters of NLS_LANG to the same values on the server side and the client side. (The value of the charset parameter on the server side is specified when the database is created and cannot be changed.) Use the SQL command ALTER SESSION to change the values of the language and territory parameters on the server side. For example, this statement changes the language parameter to French and the territory parameter to France:

ALTER SESSION
    SET NLS_LANGUAGE = French NLS_TERRITORY = France

4.1.1.2 DEVELOPER_NLS_LANG and USER_NLS_LANG

If you must use two sets of resource and message files at the same time, two other language environment variables are available:

The syntax of DEVELOPER_NLS_LANG and USER_NLS_LANG is the same as NLS_LANG.

Use these variables instead of NLS_LANG in the following situations:

If these environment variables are not specifically set, they take their default values from NLS_LANG.

4.1.2 Character sets

The character set component of the language environment variable specifies the character set in which data is represented in the user's environment. Net8 ensures that data created using one character set can be correctly processed and displayed on a system that uses a different character set, even though some characters may be represented by different binary values in the different character sets.

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.1.2.1 Character set design considerations

If you are designing a multilingual application, or even a single-language application that will run with multiple character sets, you should determine the character set most widely used at runtime and generate with the language environment variable set to that character set.

If you design and generate an application in one character set and run it in another character set, performance may suffer. Furthermore, if the runtime character set does not contain all the characters in the generate character set, question marks will appear in place of the unrecognized characters.

PDF does not support multi-byte character sets.

Note: For Form Builder, the character set used when generating is used at runtime, regardless of the character set specified in the runtime environment.

4.1.2.2 Font aliasing on Windows platforms

There may be situations where you create an application with a specific font but find that a different font is being used when you run that application. You are most likely to encounter this when using an English font (such as MS Sans Serif or Arial) in a non-Western European environment. This occurs because both Forms Developer and Reports Developer check to see if the character set associated with the font matches the character set specified by the language environment variable. If the two do not match, Forms Developer or Reports Developer automatically substitutes the font with another font whose associated character set matches the character set specified by the language environment variable. This automatic substitution assures that the data being returned from the database gets displayed correctly in the application.

Note: If you enter local characters using an English font, Windows does an implicit association with another font.

There may be cases, however, where you do not want this substitution to take place. You can avoid this substitution by mapping all desired fonts to the WE8ISO8859P1 character set in the font alias file. For example, if you are unable to use the Arial font in your application, add the following line to your font alias file:

Arial.....=Arial...WE8ISO8859P1

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.1.3 Language and territory

While the character set ensures that the individual characters needed for each language are available, support for national conventions provides correct localized display of data items.

The specified language determines the default conventions for the following characteristics:

For example, if the language is set to French, the messages:

ORA-00942: table or view does not exist
FRM-10043: Cannot open file.

will appear as:

ORA-00942: table ou vue inexistante
FRM-10043: Ouverture de fichier impossible

The specified territory determines the conventions for the following default date and numeric formatting characteristics:

For example, if the territory is set to France, numbers will be formatted using a comma as the decimal character.

4.1.4 Bidirectional support

Bidirectional support enables you to design applications in Middle Eastern and North African languages whose natural writing direction is right-to-left. Bidirectional support enables you to control:

When you are designing bidirectional applications, you may wish to use the language environment variables DEVELOPER_NLS_LANG and USER_NLS_LANG rather than NLS_LANG. For example, if you want to use an American interface while developing an Arabic application in a Windows environment, set these environment variables as follows:

DEVELOPER_NLS_LANG=AMERICAN_AMERICA.AR8MSWIN1256
USER_NLS_LANG=ARABIC_territory.charset

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.1.4.1 Bidirectional support in Form Builder

Four properties are used to specify the appearance of objects in bidirectional applications: Direction, Justification, Reading Order, and Initial Keyboard State.

Direction is an umbrella property that provides as much functionality for each object as possible. For all objects except text items and display items, the Direction property is the only bidirectional property, and its setting controls the other aspects of bidirectional function. (List items, however, include an Initial Keyboard State property.)

Text items and display items do not have a Direction property; instead, you can specifically set Justification, Reading Order, and Initial Keyboard State properties for these items.

You may restrict the keyboard state to one language. For example, setting Keyboard State to Local prevents the end user from switching the keyboard to another language.

When the bidirectional properties are set to Default, those properties inherit their values from the natural writing direction specified by the language environment variable. In most cases, this will provide the desired functionality. You only need to specify the bidirectional properties when you want to override the inherited default values.

Inheritance for bidirectional properties is as follows:

Form 

Default setting derives value from language environment variable. 

All objects, such as Alert, Block, LOV, Window, and Canvas-view 

Default setting derives value from form. 

All items, such as Text Item, Display Item, Checkbox, Button, Radio Group, and List Item 

Default setting derives value from canvas-view. 

Most properties related to bidirectional function can be retrieved and set programmatically. For more information, see the appropriate built-in subprogram description. For example, for information about getting the value of the Direction property for buttons, refer to the description for GET_ITEM_PROPERTY in the Form Builder online help.

4.1.4.2 Bidirectional support in Report Builder

Three properties are used to specify the appearance of objects in bidirectional applications: Justify, Direction (for an object), and Direction (for the report). The bidirectional properties are added to objects in the following hierarchy:

4.1.5 Unicode

Unicode is a global character set that allows multilingual text to be displayed in a single application. This enables multinational corporations to develop a single multilingual application and deploy it worldwide.

Global markets require a character set that:

4.1.5.1 Unicode support

Both Forms Developer and Reports Developer provide Unicode support. If you use Unicode, you will be able to display multiple languages, both single-byte languages such as Western European, Eastern European, Bidirectional Middle Eastern, and multi-byte Asian languages such as Chinese, Japanese, and Korean (CJK) in the same application.

Use of a single character set that encompasses all languages eliminates the need to have various character sets for various languages.

For example, to display a multi-byte language such as Japanese, the NLS_LANG environment variable must be set to (for Windows platform):

Japan_Japanese.JA16SJIS

To display a single-byte language such as German, NLS_LANG must be set to (for Windows platform):

German_Germany.WE8ISO8859P1

The obvious disadvantage of this scheme is that applications can only display characters from one character set at a time. Mixed character set data is not possible.

With the Unicode character set, you can set the character set portion of NLS_LANG to UTF8 instead of a specific language character set. This allows characters from different languages and character sets to be displayed simultaneously.

For example, to display Japanese and German together on the screen the NLS_LANG variable setting must be:

Japan_Japanese.UTF8

or

German_Germany.UTF8

Unicode capability gives the application developer and end user the ability to display multilingual text in a form. This includes text from a database containing Unicode, multilingual text, text in GUI objects (for example button labels), text input from the keyboard, and text from the clipboard. Both Forms Developer and Reports Developer currently support Unicode on Windows NT 4.0 and Windows 95 (limited support).

Note: If you develop applications for the Web, you can use Unicode because of the Unicode support provided by Java.

4.1.5.2 Font support

Both Forms Developer and Reports Developer rely on the Windows operating system for the font and input method for different languages. To enter and display text in a particular language, you must be running a version of Windows that supports that language. Font support is limited but not restricted to the Windows NT operating system font support.

Windows NT 4.0 provides True Type Big Fonts. These fonts contain all the characters necessary to display or print multilingual text. If you try to type, display, or print multilingual text and see unexpected characters, you are probably not using a Big Font. Big Fonts provided by Microsoft under NT 4.0 are as follows: Arial, Courier New, Lucida Console, Lucida Sans Unicode, and Times New Roman. Third-party Unicode fonts are also available.

4.1.5.3 Enabling Unicode support

To enable Unicode support, set NLS_LANG as follows:

NLS_LANG=language_territory.UTF8

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.2 Using National Language Support During Development

If you wish to use Form Builder, Report Builder, or Graphics Builder in a language other than English, simply specify the correct language and territory in the language environment variable. Messages, menus and menu items, dialog boxes, prompts and hints, and alerts are displayed in the appropriate language and numbers and dates in default values, ranges, and parameters are displayed in the appropriate format. If the appropriate message file is not available, the default is the US message file.

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.2.1 Format masks

4.2.1.1 Format mask design considerations

When working with date and currency fields in multilingual applications, you should make all screen items (boilerplate, text items, interface objects such as buttons and lists of values) longer to allow for translation of text and different ways of displaying data. For example, if you develop an application in American English with a 9-character DD-MON-YY date and then run the application in Norwegian, you must increase the size of the field to allow for the 10-character Norwegian date DD.MM.YYYY.

You should also consider whether you need to use the format mask characters to create special format masks or if the default format masks specified by the territory component of NLS_LANG are acceptable.

For implicit datatype conversions, PL/SQL always expects items in the American_America default format DD-MON-YY, so if you use an item whose type is territory-specific in PL/S QL, you must specify the correct format masks. Use TO_DATE to translate territory-specific items in PL/SQL.

Avoid hard-coding a string containing a month name. If a hard-coded month name is essential, avoid using the COPY built-in. If you use COPY, the month name may be incorrect, depending on which language is specified.

Language-dependent example (not recommended):

:emp.hiredate := `30-DEC-97';
copy (`30-DEC-97','emp.hiredate');

Language-independent example (recommended):

:emp.hiredate := TO_DATE(`30-12-1997','DD-MM-YYYY');

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.2.1.2 Default format masks

The language environment variable specifies the set of default format masks used to display data such as day and month names, numbers, dates, and currency. Specifically, both Forms Developer and Reports Developer use the default format masks associated with the territory specified in the current language environment variable:

For example, suppose the current territory is America. You create an item of type DATE, and enter a default value of 20-OCT-98. If you then change the territory to Norway, the default value for the item will automatically change to 20.10.1998.

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.2.1.3 Format mask characters

The following format mask characters allow you to override the default format masks.

Character  Returns 

Digit for the day (1-7) 

DY 

Name of the day (abbreviated) 

DAY 

Name of the day (padded with blanks to the length of 9 characters) 

WW 

Digit for the week, calculated by the algorithm int((day-jan1)/7) 

IW 

Digit of the ISO week 

MON 

Name of the month (abbreviated) 

MONTH 

Name of the month (padded with blanks to the length of 9 characters) 

RM 

Character for the Roman numeral month 

I, IY, IYY, IYYY 

Last one, two, or three digits of the ISO year or the ISO year, respectively 

BC, AD, B.C., A.D. 

BC or AD indicator (with or without periods) 

AM, PM, A.A., P.M. 

AM or PM indicator (with or without periods) 

Character  Returns 

International currency symbol 

Local currency symbol 

Decimal separator 

Group (thousands) separator 

4.2.2 Sorting character data

When you are designing multilingual applications, you want to sort character data according to the alphabetic conventions of a particular language rather than according to the characters' binary values. The SQL function NLSSORT makes it possible to do this.

4.2.2.1 Comparing strings in a WHERE clause

Strings in a WHERE clause are compared according to the characters' binary values: one character is considered greater than another if it has a higher binary value in the database character set. However, because the sequence of characters based on their binary values does not match the alphabetic sequence for a particular language, these comparisons yield incorrect results.

For example, suppose you have a column called COL1 that contains the values ABC, ABZ, BCD, and ÄBC. The database character set is ISO 8859/1. You write the following query:

SELECT COL1 FROM TAB1 WHERE COL1 > `B'

The query returns BCD and ÄBC since Ä has a higher numeric value than B.

Now suppose you write this query:

SELECT COL1 FROM TAB1 WHERE NLSSORT(COL1) > NLSSORT(`B')

If the language component of the language environment variable is set to German, the query returns BCD, because Ä comes before B in the German alphabet. If the language component of the language environment variable is set to Swedish, the query returns BCD and ÄBC, because Ä comes after Z in the Swedish alphabet.

4.2.2.2 Controlling an ORDER BY clause

If the language component of the language environment variable is set correctly, it is not necessary to use NLSSORT in an ORDER BY clause.

The following query yields a correct result:

SELECT ENAME FROM EMP
ORDER BY ENAME

4.2.3 NLS parameters

4.2.3.1 Using ALTER SESSION

You can use the SQL command ALTER SESSION to override the NLS defaults. For example, suppose you create some parameters (such as language, territory, etc.), and a user specifies values for them: you could then alter the session as they specified.

In Form Builder, you can specify any of the following NLS parameters for the ALTER SESSION command. However, for Report Builder and Graphics Builder, you can only specify the NLS_SORT parameter.

Parameter  Description 

NLS_LANGUAGE 

Language used by the server to return messages and errors 

NLS_TERRITORY 

Territory used for default date and currency masks 

NLS_DATE_FORMAT 

Default format mask used for dates 

NLS_DATE_LANGUAGE 

Default language used for dates 

NLS_NUMERIC_CHARACTERS 

Decimal character and group separator 

NLS_ISO_CURRENCY 

ISO international currency symbol 

NLS_CURRENCY 

Local currency symbol 

NLS_SORT 

Character sort sequence 

NLS_CALENDAR 

Current calendar system 

For example, this statement changes the decimal character to a comma and the group separator to a period:

ALTER SESSION
    SET NLS_NUMERIC_CHARACTERS = `,.'

These new characters are returned when you use their number format elements D and G:

SELECT TO_CHAR(SUM(sal), `L999G999D99') Total FROM emp

TOTAL
---------------
    FF29.025,00

This statement changes the ISO currency symbol to the ISO currency symbol for the territory America:

ALTER SESSION
    SET NLS_ISO_CURRENCY = America

The ISO currency symbol defined for America is used:

SELECT TO_CHAR(SUM(sal), `C999G999D99') Total FROM emp

TOTAL
---------------
    USD29.025,00

This statement changes the local currency symbol to DM:

ALTER SESSION
    SET NLS_CURRENCY = `DM'

The new local currency symbol is returned when you use the L number format element:

SELECT TO_CHAR(SUM(sal), `L999G999D99') Total FROM emp

TOTAL
---------------
    DM29.025,00

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.2.3.2 Using NLS parameters in SQL functions

Wherever you use SQL, you can use the following NLS parameters to override default NLS behavior.

SQL Function  NLS Parameter 

TO_DATE 

NLS_DATE_LANGUAGE 

 

NLS_CALENDAR 

TO_NUMBER 

NLS_NUMERIC_CHARACTERS 

 

NLS_CURRENCY 

 

NLS_ISO_CURRENCY 

TO_CHAR 

NLS_DATE_LANGUAGE 

 

NLS_NUMERIC_CHARACTERS 

 

NLS_CURRENCY 

 

NLS_ISO_CURRENCY 

 

NLS_CALENDAR 

NLS_UPPER 

NLS_SORT 

NLS_LOWER 

NLS_SORT 

NLS_INITCAP 

NLS_SORT 

NLSSORT 

NLS_SORT 

4.2.3.3 Form Builder NLS parameters

You can use Form Builder built-in functions to obtain the current value of the language environment variables for use in PL/SQL code:

Environment Variables  DEVELOPER_NLS_LANG (defaults to NLS_LANG)  USER_NLS_LANG (defaults to NLS_LANG) 

Built-in 

GET_FORM_PROPERTY 

GET_APPLICATION_PROPERTY 

Parameter 

MODULE_NLS_LANG 

USER_NLS_LANG 

Because both USER_NLS_LANG and DEVELOPER_NLS_LANG default to the value of NLS_LANG, the Form Builder NLS parameters will hold the value of NLS_LANG if either variable is not specifically set.

Both Form Builder NLS parameters have four variations which allow you to retrieve either the complete environment variable or a specific portion of it. This table shows the four parameters of the GET_APPLICATION_PROPERTY built-in that return the USER_NLS_LANG environment variable:

Parameter  Returns 

USER_NLS_LANG 

Entire USER_NLS_LANG variable 

USER_NLS_LANGUAGE 

Language portion only 

USER_NLS_TERRITORY 

Territory portion only 

USER_NLS_CHARACTER_SET 

Character set portion only 

To retrieve the DEVELOPER_NLS_LANG environment variable, call GET_FORM_PROPERTY using the MODULE_NLS_LANG parameter.

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.2.3.4 Report Builder report definition files

When using reports in character mode, you should define the physical page width of a report as one character less than the page width defined in the printer definition file (.PRT file). Otherwise, multi-byte characters might start on the last character space of a line and have to overflow to the next line in order to complete. For example, if the physical page width is 80 characters and the width in the printer definition is 80 characters, a multi-byte character might start on the 80th character. Since multi-byte characters may not be separated, the line would have to overflow to an 81st character in order to complete the multi-byte character. To avoid this, the physical page width should be set to 79 for the report.

The following Arabic and Hebrew specific NLS parameters can be set in the printer definition file:

Use  To  Values 

nls locale 

set the locale of printing engine. 

hebrew or arabic 

nls datastorageorder 

set logical or visual data storage 

logical or visual 

nls contextuallayout 

perform pre contextual layout for Arabic printers 

no or yes 

nls contextualshaping 

perform pre contextual shaping for Arabic printers 

no or yes 

nls pcharste 

specify the character set of the printer 

any character set 

4.3 Translating Your Applications

In any Forms or Reports application, the user sees the following:

If the language environment variable is set correctly and the appropriate message files are available, translation of messages in the first two categories is done for you. To translate messages in the third category, use one of the methods described in the following sections.

Refer to Section 4.1.1, "The language environment variables" for more information on the language environment variables.

4.3.1 Translating your applications using Translation Builder

Translation Builder can help you translate menus, boilerplate text, item labels, messages, and hints defined on item property sheets in your applications. Using Translation Builder, you can generate separate binary files for each language.

If you plan to use Translation Builder to translate your application, develop the application in the following stages:

4.3.1.1 Advantages

This is the simplest way to implement multiple language applications quickly. With this approach, you can use Translation Builder for maximum efficiency. If you have a stable application, this approach will work well for you.

For example, if you create an application in four languages and then change a field label, you would do the following:

4.3.1.2 Disadvantages

If your applications must support multiple languages simultaneously, you must use the runtime language switching approach instead.

4.3.2 Translating your applications using runtime language switching

A small number of applications must support multiple languages simultaneously. For example, the application may begin by displaying a window in English which must stay up throughout the application, while an end user may press a button on that window to toggle the prompts into French, and then back into English.

If your application requires runtime language switching, you can include more than one language in a single application as long as they share the same character set, but you cannot use Translation Builder to locate translatable text if you are dynamically populating the text at runtime. Instead, you would build case structures (IF...THEN...ELSIF) to change the application to another language by checking the value of the NLS environment variable using the GET_FORM_PROPERTY built-in.

Using the runtime language switching approach, you could develop your application in the following stages:

Form Builder supports attaching multiple libraries, so you can use one library specifically for messages that will be translated, and other libraries for other purposes.

4.3.2.1 Advantages

The main advantage of this approach is it allows you to support sophisticated applications which may be highly dynamic. In these cases, this approach avoids some maintenance problems, because you do not have to generate separate files for each language each time the application changes.

4.3.2.2 Disadvantages

This approach is more complicated, because it involves considerable effort to create the language-specific message storage, population, and maintenance involved and to perform the translation manually. For example, you would set up a WHEN-NEW-FORM-INSTANCE trigger to set the labels for each button, pulling the correct labels from an attached library, based on the value of the NLS environment variable.

4.3.3 Using PL/SQL libraries for strings in code

While Translation Builder helps you translate strings in your application's user interface, it cannot pull out string constants in PL/SQL triggers and procedures. Manual translation is required for constant text within a PL/SQL block because that text is not clearly delimited, but is often built up from variables and pieces of strings. To translate these strings, you can use PL/SQL libraries to implement a flexible message structure.

Refer to Section 4.3.1, "Translating your applications using Translation Builder" for more information on translating strings in your application's user interface.

You can use the attachable PL/SQL libraries to implement a flexible message function for messages that are displayed programmatically by the built-in routines MESSAGE or CHANGE_ALERT_MESSAGE, or by assigning a message to a display item from a trigger or procedure. The library can be stored on the host and dynamically attached at runtime. At runtime, based on a search path, you can pull in the library attached to the form. For example, a library might hold only the Italian messages:

FUNCTION nls_appl_mesg(index_no NUMBER)
RETURN CHAR
IS
   msg CHAR(80);
BEGIN
   IF      index_no = 1001 THEN
       msg := `L''impiegato che Voi cercate non esiste...';
   ELSIF   index_no = 1002 THEN
       msg := `Lo stipendio non puo essere minore di zero.';
   ELSIF   ...
   :
   ELSE
       msg := `ERRORE: Indice messaggio inesistente.';
   END IF;
   RETURN msg;
END;

A routine like this could be used anywhere a character expression would normally be valid. For example, to display an alert with the appropriately translated application message, you might include the following code in your form:

Change_Alert_Message(`My_Error_Alert', nls_appl_mesg(1001));
n := Show_Alert(`My_Error_Alert');

To change the application to another language, simply replace the PL/SQL library containing the nls_appl_msg function with a library of the same name containing the nls_appl_mesg function with translated text.

4.3.4 Screen design considerations

When you are designing multilingual applications, remember to leave extra space in the base screen design for widgets and boilerplate labels. To accommodate multiple character sets and allow for expansion caused by translation, a rule-of-thumb is to leave 30% white space around fields, borders, and boilerplate text.

Specifically:


Prev Next
Oracle
Copyright © 2000 Oracle Corporation.

All Rights Reserved.

Library

Solution Area

Contents

Index