Oracle Forms Developer and Reports Developer Release 6i: Guidelines for Building Applications A73073-01 |

|  | 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:

- use international character sets (including multi-byte character sets).

- display data according to the appropriate language and territory conventions.

- extract strings that appear in your application's user interface and translate them.

### 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 language for messages displayed to the user, such as the "Working..." message

- the default format masks used for DATE and NUMBER datatypes

- the sorting sequence

- the character set

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:

- DEVELOPER_NLS_LANG specifies the language for the Builder.

- USER_NLS_LANG specifies the language for the Runtime component.

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:

- You prefer to use the Builder in English, but you are developing an application for another language, the two variables allow you to use different language settings for the Builder and Runtime.

- You are creating an application to run in a language that uses a bidirectional character set.

- You are creating an application to run in a language for which a local-language version of the Builder is not currently available.

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:

- language for server messages

- language for day and month names and their abbreviations (specified in the SQL functions TO_CHAR and TO_DATE)

- symbols for equivalents of AM, PM, AD, and BC

- default sorting sequence for character data when ORDER BY is specified (GROUP BY uses a binary sort, unless ORDER_BY is specified)

- writing direction

- affirmative/negative response strings

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:

- date format

- decimal character and group separator

- local currency symbol

- ISO currency symbol

- week start day

- credit and debit symbol

- ISO week flag

- list separator

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:

- layout direction, which includes displaying items with labels at the right of the item and correct placement of check boxes and radio buttons.

- reading order, which includes right-to-left or left-to-right text direction.

- alignment, which includes switching point-of-origin from upper left to upper right.

- initial keyboard state, which controls whether Local or Roman characters will be produced automatically when the user begins data entry in forms (the end user can override this setting).

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:

Module

Boilerplate

Field

External Boilerplate

Button

Parameter Form Boilerplate

Objects not in this list either do not require bidirectional support (for example, images) or they are defaulted from one of the above object's properties.

### 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:

- allows a single implementation of a product for all languages, yet is simple enough to be implemented everywhere

- contains all major living scripts

- supports multilingual users and organizations

- enables worldwide interchange of data via the Internet

#### 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:

- in the Builder: When the Builder displays default values for items, ranges, or parameters

- at runtime: If a user enters data in a text item whose type is territory-specific, such as DATE or NUMBER

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
--- | ---
D | 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
--- | ---
C | International currency symbol
L | Local currency symbol
D | Decimal separator
G | 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:

- error messages from the database

- runtime error messages produced by Forms Developer or Reports Developer

- messages and boilerplate text defined as part of the application

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:

- Create one basic definition (for example, .FMB) in the source language.

- Use Translation Builder to extract strings for translation, translate the strings into one or more languages, and store the translated strings back into the definition.

- Manually translate messages in PL/SQL libraries. (Refer to Section 4.3.3, "Using PL/SQL libraries for strings in code" for more information on translating messages that are displayed programmatically.)

- Use the Generate component to generate a binary version (for example, .FMX) for each target language.

#### 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:

- Make the change in the Builder and save the change in the definition file.

- Use Translation Builder to translate the new field label and insert the new messages into the definition file.

- Regenerate to create a binary file containing the new label.

#### 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:

- Develop the entire application for one language, including libraries.

- Manually translate each library.

- Design boilerplate labels as appropriately sized display items that are dynamically populated at runtime.

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:

- Prompt on left of field: Allow for 30% expansion to the left of the prompt.

- Prompt above field: Allow for 30% expansion to the right of the prompt.

- Buttons, checkboxes, radio groups, and poplists: Allow for 30% expansion.

- Form titles: Size any bounding box so the title can expand to the right by 30%.

- Display-only fields: Size 30% wider than needed for base language.

- All widgets: Make widgets large enough to accommodate translation. For example, buttons should be large enough to hold translated labels. Check button height as well as length to be sure the height of the button will accommodate the tallest character you need to use. Calculate pixels needed to render Kanji characters.

| Copyright © 2000 Oracle Corporation. All Rights Reserved. |
|  | Contents | Index