Volume 7A: XView Programming Manual

22.2.1.5 Examples

The following three examples retrieve the same strings, but have different effects on the text

domain. The first example does not change the current text domain. The second and third

examples change the current text domain to library_error_strings, then retrieve the

foreign language string of wrongbutton.

message = dgettext("library_error_strings",

"wrongbutton");

textdomain("library_error_strings");

message = gettext("wrongbutton");

textdomain("library_error_strings");

message = dgettext("", "wrongbutton"); \\* "" = current domain *\\

22.2.1.6 XV_LOCALE_DIR

If XV_LOCALE_DIR is set in xv_init(), XView calls bindtextdomain() on the appli-

cation’s behalf to prepend the pathname specified by XV_LOCALE_DIR to the default domain

path list. All unbound text domains would be located in the directory with the general format:

<XV_LOCALE_DIR>/<Display Language Setting>/LC_MESSAGES/domain

"domain” is the name of the text domains. The default value of XV_LOCALE_DIR is

$OPENWINHOME/lib/locale.

An example, using XV_LOCALE_DIR follows:

xv_init(XV_INIT_ARGS, argc, argv,

XV_LOCALE_DIR, "/app_home/lib/locale",

NULL);

22.2.2 Creating a Text Domain

Once the program is written using gettext() and dgettext(), text domains are created

using the following procedures:

1. For example, you could run xgettext on the following source file fragment (see the

man page for xgettext for proper usage):

message1 = dgettext("library_error_string", "Save");

message2 = dgettext("library_error_string", "File");

message3 = dgettext("library_error_string", "Edit");

Internationalization

Internationalization 547

This filter extracts the strings from the source files, and places them in a portable message

file. The format of the portable message file produced is shown below:

domain "library_error_strings

msgid "File"

msgstr

msgid "Save"

msgstr

msgid "Edit"

msgstr

The xgettext filter currently does not expand #define commands. If you have

#define strings which need to be extracted, then you need to run your application

through the C preprocessor as follows:

cc -P file.c

This runs the source file through the C preprocessor only, and outputs to a file with a suf-

fix, .i. You should then run this .i file through xgettext to extract all strings:

xgettext xgettext options file.i

This will produce a file called library_error_string.po.

2. Add the foreign language equivalents for all the native language strings in the portable

message file between quotes next to msgstr. Use a plain text editor that supports the

character set/encoding for the language.

domain "library_error_strings

msgid "File"

msgstr "<french for File>"

msgid "Save"

msgstr "<french for Save>"

msgid "Edit"

msgstr "<french for Edit>"

If you wish to create multiple text domains, you may separate the related text strings into

separate files. Be sure that the first line of every file consists of a domain line at the begin-

ning of each file. You may also have multiple text domains within the same file. To do

this, simply start each new domain with the line:

domain "domain_name"

where domain_name is the name of the text domain. Note that the message identifiers and

strings of a particular domain must be in the same file under the same domain name.

3. Run the msgfmt program on each portable message file to produce the text domain file:

msgfmt library_error_string.po

This produces the text domain file library_error_string.mo, which contains the messages

compiled in an internal format. The text domain file is in binary format, and is not inter-

changeable between CPU architectures. It cannot be edited using an editor, and must be

created using msgfmt.

4. Move each text domain to the directory under the path specified as follows:

<XV_LOCALE_DIR>/locale/LC_MESSAGES

548 XView Programming Manual

As mentioned previously, gettext() and dgettext() search the text domain for the

native language text or key value, then extract the corresponding foreign language text.

The key is a unique name that identifies the string to be retrieved. The key does not have

to be the native language string, but the native language string is a good choice since it

tends to be self-documenting.

22.2.3 New and Enhanced XView Attributes for gettext()

NOTICE_MESSAGE_STRING specifies text to print in a notice. NOTICE_MESSAGE_STRING is

necessary when using gettext() to get a notice message. The value of this attribute is a

single NULL-terminated string, which may contain “\n” as a line break. NOTICE_MES-

SAGE_STRINGS

specifies the text to print in a notice. The value is NULL-terminated list of

strings, which may contain “\n” as a line break. NOTICE_MESSAGE_STRINGS_ARRAY_PTR

specifies the text to print in a notice. The value is a variable pointing to a NULL-terminated

array of strings, which may contain “\n” as a line break.

This example shows how notices are displayed in XView Version 2.

result = notice_prompt( panel , NULL,

NOTICE_BUTTON, "Update changes" , 101,

NOTICE_BUTTON, "Ignore changes" , 102,

NOTICE_BUTTON, "Destroy everything" ,103,

NOTICE_MESSAGE_STRINGS, "Press button,"

"then go home" ,

NULL,

NULL);

This example uses NOTICE_MESSAGE_STRING and makes the same notice window as the pre-

vious example.

result = notice_prompt( panel , NULL,

NOTICE_BUTTON, "Update changes", 101,

NOTICE_BUTTON, "Ignore changes", 102,

NOTICE_BUTTON, "Destroy everything", 103,

NOTICE_MESSAGE_STRING, "Press button,\nthen go home" ,

NULL);

This example shows how to embed gettext().

result = notice_prompt( panel , NULL,

NOTICE_BUTTON, gettext("Update changes" ), 101,

NOTICE_BUTTON, gettext("Ignore changes" ), 102,

NOTICE_BUTTON, gettext(" Destroy everything" ), 103,

NOTICE_MESSAGE_STRING, gettext(" Press button,\n then go home" ),

NULL);

Internationalization

Internationalization 549

22.3 Object Layout and Customization

The layout of screen objects (buttons, panel items, etc.) needs to change when the dimensions

of the strings within those objects change. For example, a button string in French might be

much longer than the same button string in English, thus requiring other buttons to be reposi-

tioned. Another example of object layout changes are objects that have to be repositioned to

accommodate locale-specific representations such as date or time. A mechanism is required

to alter the layout during localization.

22.3.1 Implicit and Explicit

Object layout of an XView application may be implicit or explicit. Using explicit layout, the

application specifies x and y coordinates for the objects in the application. Implicit layout

relies on certain defaults that are built into the toolkit. Thus, if a series of panel items is

created, and no layout information is explicitly specified, the panel package will position the

items based on default spacing rules. For example, one rule is to start a new row when a

panel item extends past the edge of a panel.

Implicit positioning may be all that is required to localize an application. When the locale is

switched, the new strings are picked up and the panel package automatically adjusts the lay-

out of the panel items based on the dimensions of the new strings.

Other scenarios may exist, however, where explicit layout is required. One situation where

implicit positioning does not provide a satisfactory layout is when switching locales. Another

scenario requiring explicit repositioning is when accommodating changes in format when

locales are switched. For example, the date representation in the United States is mm/dd/yy,

while in India the date is represented as dd/mm/yy. Reliance on such explicit formats requires

modification during localization.

The attributes, XV_USE_DB and XV_INSTANCE_NAME, allow developers to specify customiz-

able attributes. These attributes can be used to specify explicit object layout.

22.3.2 Layout and Customization API

22.3.2.1 XV_LOCALE_DIR

Each application may have one or more locale-specific application defaults files. These files

provide layout information and any other data stored under the X Resource Manager that is

specific to a given locale.

The directory structure for the locale-specific defaults files used by the layout scheme is:

<XV_LOCALE_DIR>/locale/app-defaults/<appname>.db (read first)

<XV_LOCALE_DIR>/locale/app-defaults/<appname>/*.db

where locale is the current setting of Basic Locale.

550 XView Programming Manual

Typically an application would have its locale-specific application defaults file (one file) in:

<XV_LOCALE_DIR>/locale/app-defaults/<appname>.db

If the application wants to group its application defaults into multiple files, they can be

placed in the directory:

<XV_LOCALE_DIR>/locale/app-defaults/<appname>/*.db

22.3.2.2 XV_USE_DB

XV_USE_DB can be used to specify a set of attributes that are to be searched in the X11

Resource Manager database. XV_USE_DB takes a NULL-terminated list of attribute value pairs

as its values. During program execution, each attribute in this NULL-terminated list is looked

up in the X11 Resource Manager database. If the attribute is not found in the database, then

the value specified in the attribute-value pair is used as the default value.

22.3.2.3 XV_INSTANCE_NAME

The attribute

XV_INSTANCE_NAME is used to associate an instance name with an XView

object. The instance name is used to construct the key value (resource name) used by the

resource manager to perform the lookup. The key value is constructed by concatenating the

instance names of all objects in the current object’s lineage, starting with the name of the

application or whatever was passed in with the -name command-line option. The XView

attribute name remains in lowercase.

An example using

XV_INSTANCE_NAME is shown below. Assume that the application name is

“app.” The key value is constructed by concatenating “app,” “frame1,” and “panel1.” Thus,

resource files containing entries such as the following would be specified as in Example 22-1:

app.frame1.panel1.xv_x: 20

app.frame1.panel1.xv_y: 20

Example 22-1. Using

XV_INSTANCE_NAME

(void)xv_init(XV_USE_LOCALE, TRUE,

XV_INIT_ARGC_PTR_ARGV, &argc, argv,

...

NULL);

frame = (Frame)xv_create(0, FRAME,

XV_INSTANCE_NAME, "frame1" ,

NULL);

panel = (Panel)xv_create(frame, PANEL,

XV_INSTANCE_NAME, "panel1" ,

XV_USE_DB,

XV_X, 10,

XV_Y, 15,

NULL,

NULL);

Internationalization

Internationalization 551