Volume 7A: XView Programming Manual

Table 22-3. XView Locale Resources

Locale Parameter Resource Name

Basic Setting basicLocale

Display Language displayLang

Input Language inputLang

Numeric Format numeric

Time Format timeFormat

The example below shows locale resource entries in the X resource database. This example

shows the resources set to the value of “C.” This is the default locale on most operating sys-

tems. As far as character input/output is concerned, “C” is synonymous with 7-bit ASCII.

*basicLocale: C

*displayLang: C

*inputLang: C

*numeric: C

*timeFormat: C

This example shows the resource set to the value “C”. This value specifies the English lan-

guage (American).

22.1.5.2 ANSI-C/POSIX

Internally, XView uses several standard

ANSI-C/POSIX functions. The setlocale() is an

internal function that should not be used in application programs. If locale attributes, com-

mand-line options, or resources are not specified, XView uses environment variables to set

locale information. This method follows the ANSI-C/POSIX specification for locale

announcement. The environmental variables are the same as the POSIX locale categories.

POSIX categories are shown in Table 22-4.

Table 22-4. POSIX Categories

OPEN LOOK Category POSIX Category

Basic Setting LC_CTYPE/LANG*

Display Language LC_MESSAGES

Input Language n/a

Numeric Format LC_NUMERIC

Time Format LC_TIME

n/a LC_MONETARY

n/a LC_COLLATE

*

LANG

(Basic Setting above) is not one of the POSIX categories, but is a convenience environment variable used to set

the default for other locales. Basic Locale sets

LC_CTYPE, LC_MONETARY, and LC_COLLATE. Input Language will be

the same as

LC_CTYPE.

542 XView Programming Manual

22.1.6 Limits and Restrictions

The Basic Locale setting determines the character set used by XView. The other locale

categories can differ from the basic setting, but they cannot require a different character set

from the Basic Locale. For example, setting the Basic Locale to “fr” (French) and the Display

Language to “ja” (Japanese) will not work because the French and Japanese locales require

different character sets.

The following restrictions thus apply:

1. If basic locale setting is the “C” locale, then all other locale categories must be in the “C”

locale.

2. If the Basic Locale is set to a locale other than the “C” locale, then all other locale

categories must be set either to a locale that uses the same character set as the basic set-

ting, or to the “C” locale.

22.2 Localized Text Handling

When creating an internationalized application, developers need to write text strings in their

native language (error messages, menu labels, button labels) and have those strings appear in

foreign languages based on the locale established in the environment. Note that the term

“foreign language” refers to non-native languages. XView allows you to define any lan-

guage as the native language and any other language as the foreign language.

Localized text handling allows a developer to write text strings in the native language and

have those strings retrieved in a foreign language. To implement localized text handling in an

XView program, the developer must perform the following tasks:

1. For all displayable text strings, use the string as an argument in the gettext() or

dgettext() functions. These functions accept native language strings as arguments,

and return the equivalent foreign language strings.

2. Extract the native language text strings used with gettext() and dgettext() from

the source and store them in a portable message file. This extraction can be done by

hand, or through the source filter xgettext.

3. Provide the foreign language equivalent for each text string, and put it in the portable

message file. The portable message file can be edited using any plain text editor which

supports both the native and foreign language.

4. Run the msgfmt program on the portable message file to create a text domain. Here is

an explanation on domains. The complete list of messages that exists in a system can be

divided in two different ways: Those that belong to a particular language can be grouped

together in a locale.

Those that logically belong to a “function” (for lack of a better word), “package,”

“library,” etc., can be grouped together in a “text domain.” Messages are grouped in

domains for convenience and maintenance. A domain contains messages from its

Internationalization

Internationalization 543

“group” in all the valid languages of the system. Likewise, a locale contains all the mes-

sages in a specific language (this covers all domains of the system). Example of domains

are, “panel_labels,” “library_error_messages,” “menu_labels,” and so on.

So, to obtain the correct translation of a message string, one needs to know what language

it is to be displayed in (locale - French, Japanese, etc), and which logical group it belongs

to (domain - error messages, button labels, etc.) The text domain is in binary file format

and is not interchangeable between CPU architectures. This file cannot be edited using an

editor; it must be created using msgfmt.

XView follows the UniForum Messaging Proposal (1003.1b) specification of gettext, dget-

text, text domain, and portable source file format for messages (PSFFM).

22.2.1 Localized Text Handling – Application Programmer Interface

Several functions support localized text handling. They are described in this section.

22.2.1.1 gettext()

The procedure gettext() retrieves the foreign language string for the passed string. The for-

mat of gettext() is:

char *

gettext(msg_id)

char *msg_id;

where “msg_id” is the native language string for which the foreign language equivalent is

required. The locale used for retrieval is the current setting of the Display Language cate-

gory (LC_MESSAGES). The domain used is the “current domain,” or the domain set by the last

call to “textdomain( ).” If a call to textdomain( ) has not been made, the default domain is

used.

If gettext( ) cannot find the foreign language equivalent for “msg_id,” then “msg_id” itself is

used.

The example below searches the current text domain for the foreign language string that is

identified by the key “wrongbutton.” The foreign language string is then assigned to “mes-

sage:”

message = gettext("wrongbutton");

544 XView Programming Manual

22.2.1.2 dgettext()

Another function, dgettext(), allows you to specify the text domain from which to

retrieve the foreign language string without changing the current text domain. Its format is:

char *

dgettext (domain_name, string)

char *domain_name;

char *string;

Where domain_name is the text domain containing the desired foreign language equivalent,

and string is the native language string for which the foreign language equivalent is desired.

The following example searches for the foreign language equivalent wrongbutton in the

text domain library_error_strings, then assigns the result to message. The cur-

rent text domain, which was active before this call, is not changed.

message = dgettext("library_error_strings",

"wrongbutton");

22.2.1.3 textdomain()

Use textdomain() to specify the current text domain. It has the following format:

char *

textdomain(domain_name)

char *domain_name;

Where domain_name is the desired current text domain.

The following example sets the current text domain to library_error_strings. All

subsequent gettext() calls automatically search library_error_strings for the

foreign language equivalent.

textdomain("library_error_strings");

The value of the current text domain can be queried as follows:

current_domain = textdomain(NULL);

The domain may be set to the implementation-defined default domain by calling

textdomain() with a domain name set to an empty string. Such a call to

textdomain() will also return the implementation-defined default domain. (Refer to the

man page on textdomain for specific information on the default domain for your operating

system.) For example:

default_domain = textdomain("");

Multiple text domains can be used within the same application. This allows different types of

strings to be grouped into separate text domains. For example, one text domain might contain

error messages from the XView library, a second text domain might contain XView menu

and button text, and a third might contain strings from the application.

Internationalization

Internationalization 545

22.2.1.4 bindtextdomain()

The current Uniforum messaging proposal does not specify a method for identifying the loca-

tion of text domains in the file system. The function bindtextdomain() performs this

function. The function defines the location of the text domain files to the library. The format

of the bindtextdomain() call is:

char *

bindtextdomain(domain_name, binding)

char *domain_name;

char *binding;

The following example sets the binding for the text domain library_error_strings to

/home/myapp/lib/locale :

bindtextdomain("library_error_strings", "/home/myapp/lib/locale");

All subsequent gettext() and dgettext( ) calls for the text domain library_error_strings will

look in:

/home/myapp/lib/locale/<Display Language Setting>/LC_MESSAGES

for the message file library_error_strings.mo.

The bindtextdomain() function also has a default domain binding. The default domain

binding is applied to any text domains that haven’t been bound explicitly by a

bindtextdomain() call. Unlike the other bindings, the default binding is actually a list

of directories that are searched in order. There is always at least one directory in the list:

/usr/lib/locale.

Additional directories can be added to the list as follows:

bindtextdomain("", "/home/myapp/lib/locale");

Directories are searched in the order in which they are added to the list. In the above

example, /usr/lib/locale would be searched first followed by /home/myapp/lib/locale .

An opaque snapshot of the state of the default binding list can be taken with the following:

(char *) state = bindtextdomain("", NULL);

Note that this is similar in principle to using setlocale():

setlocale(LC_ALL, NULL);

The state can be restored at a later time using the following:

bindtextdomain("", state);

546 XView Programming Manual