HP OpenVMS Systems Documentation

Content starts here
Common Desktop Environment: Internationalization Programmer's Guide

2 Internationalization and the Common Desktop Environment


Contents of Chapter:
Locale Management
Font Management
Matching Fonts to Character Sets
Font Objects
Font Set and Font List Syntax
Font Functions
Font Charsets
Default Font Set Per Language Group
Drawing Localized Text
Simple Text
XmString (Compound String)
Inputting Localized Text
Basic Prompts and Dialogs
Input within a DrawingArea Widget
Application-Specific and Language-Specific Intermediate Feedbacks
Text and TextField Widget
Character Input within Customized Widgets Not Using Text[Field] Widgets
XIM Management
XIM Event Handling
XIM Callback
Extracting Localized Text
Resource Files
Message Catalogs
Private Files
Message Guidelines
Message Extraction Functions
XPG4/Universal UNIX Messaging Functions
XPG4 Messaging Examples
Xlib Messaging Functions
Xlib Message and Resource Facilities
Localized Resources
Labels and Buttons
List Resources
Title
Text Widget
Input Method (Keyboards)
Pixmap (Icon) Resources
Font Resources
Operating System Internationalized Functions
Multiple environments may exist within a common open system for support of different national languages. Each of these national environments is called a locale, which considers the language, its characters, fonts, and the customs used to input and format data. The Common Desktop Environment is fully internationalized such that any application can run using any locale installed in the system.

Locale Management

For the desktop, most single-display clients operate in a single locale that is determined at run time from the setting of the environment variable, which is usually $LANG. The Xm library (libXm) can only support a single locale that is used at the time each widget is instantiated. Changing the locale after the Xm library has been initialized may cause unpredictable behavior.

All internationalized programs should set the locale desired by the user as defined in the locale environment variables. For programs using the desktop toolkit, the programs call the XtSetLanguageProc() function prior to calling any toolkit initialization function; for example, XtAppInitialize(). This function does all of the initialization necessary prior to the toolkit initialization. For nondesktop programs, the programs call the setlocale() function to set the locale desired by the user at the beginning of the program.

Locale environment variables (for example, LC_ALL, LC_CTYPE, and LANG) are used to control the environment. Users should be aware that the LC_CTYPE category of the locale is used by the X and Xm libraries to identify the locale-specific features used at run time. Yet, the LC_MESSAGES category is used by the message catalog services to load locale-specific text. Refer to "Extracting Localized Text" for more information. Specifically, the fonts and input method loaded by the toolkit are determined by the setting of the LC_CTYPE category.

String encoding (for example, ISO8859-1 or Extended UNIX Code (EUC), in an application's source code, resource files, and User Interface Language (UIL) files) should be the same as the code set of the locale where the application runs. If not, code conversion is required.

All components are shipped as a single, worldwide executable and are required to support the R5 sample implementation set of locales:
US, Western/Eastern Europe, Japan, Korea, China, and Taiwan.

Applications should be written so that they are code-set-independent and include support for any multibyte code set.

The following are the functions used for locale management:

  • XtSetLanguageProc()
  • setlocale()
  • XSupportsLocale()
  • XSetLocaleModifiers()

Font Management

When rendering text in an X Windows client, at least two aspects are sensitive to internationalization:

  • Obtaining the localized text itself

  • Selecting the one or more fonts that contain all the glyphs needed to render the characters in the localized text.

"Extracting Localized Text" describes how to choose the correct fonts to render localized text.

Matching Fonts to Character Sets

A font contains a set of glyphs used to render the characters of a locale. However, you may also want to do the following for a given locale:

  • Determine the fonts needed
  • Specify the necessary fonts
  • Determine the charset of a font in a resource file
  • Choose multiple fonts per locale

The last two fields of a font XFLD identify which glyphs are contained in a font and which value is used to obtain a specific glyph from the set. These last two fields identify the encoding of the glyphs contained in the font.

For example:

-adobe-courier-medium-r-normal--24-240-75-75-m-150-iso8859-1

The last two fields of this XLFD name are iso8859 and 1. These fields specify that the ISO8859-1 standard glyphs are contained in the font. Further, it specifies that the character code values of the ISO8859-1 standard are used to index the corresponding glyph for each character.

The font charset used by the application to render data depends on the locale you select. Because the font charset of the data changes is based on the choice of locale, the font specification must not be hardcoded by the application. Instead, it should be placed in a locale-specific app-defaults file, allowing localized versions of the app-defaults file to be created.

Further, the font should be specified as a fontset. A fontset is an Xlib concept in which an XLFD is used to specify the fonts. The font charset fields of the XLFD are specified by the Xlib code that creates the fontset and fills in these fields based on the locale that the user has specified.

For many languages (such as Japanese, Chinese, and Korean), multiple font charsets are combined to support single encoding. In these cases, multiple fonts must be opened to render the character data. Further, the data must be parsed into segments that correspond to each font, and in some cases, these segments must be transformed to convert the character values into glyphs indexes. The XFontset, which is a collection of all fonts necessary to render character data in a given locale, also deals with this set of problems. Further, a set of rendering and metric routines are provided that internally take care of breaking strings into character-set-consistent segments and transforming values into glyph indexes. These routines relieve the burden of the application developer, who needs only the user fontsets and the new X11R5 rendering and metric application program interfaces (APIs).

Font Objects

This section describes the following font objects:

  • Font sets
  • Fonts
  • Font lists

Font Sets

Generally, all internationalized programs expecting to draw localized text using Xlib are required to use an XmFontSet for specifying the locale-dependent fonts. Specific fonts within a font set should be specified using XLFD naming conventions without the charset field specified. The resource name for an XFontset is *fontSet. Refer to "Localized Resources" for a list of font resources.

Applications directly using Xlib to render text (as opposed to using XmString functions or widgets) may take advantage of the string-to-fontSet converter provided by Xt. For example, the following code fragment shows how to obtain a fontset when using Xt and when not using Xt:

/* pardon the double negative... means "If using Xt..." */
#ifndef NO_XT
typedef struct {
        XFontSet fontset;
            char *foo;
} ApplicationData,  *ApplicationDataPtr;
static XtResource my_resources[] = {
    { XtNfontSet, XtCFontSet, XtRFontSet, sizeof (XFontSet),
    XtOffset (ApplicationDataPtr, fontset), XtRString,
     "*-18-*"}}
#endif /* NO_XT */
...
#ifdef NO_XT
fontset = XCreateFontSet (dpy, "*-18-*", &missing_charsets,
    &num_missing_charsets. &default_string);
if (num_missing_charsets > 0) {
    (void) fprintf(stderr, "&s: missing charsets.\n",
                    program_name);
    XFreeStringList(missing_charsets);
}
#else
XtGetApplicationResources(toplevel, &data, my_resources,
       XtNumber(my_resources), NULL, 0);
fontset = data.fontset;
#endif /* NO_XT */

Fonts

Internationalized programs should avoid using fonts directly, that is, XFontStruct, unless they are being used for a specific charset and a specific character set. Use of XFontStruct may be limiting if the server you are connecting to does not support the specific charsets needed by a locale. The resource name for an XFontStruct is *font.

Font Lists

All programs using widgets or XmString to draw localized text are required to specify an XFontList name for specifying fonts. A font list is a list of one or more fontsets or fonts, or both. It is used to convey the list of fonts and fontsets a widget should use to render text. For more complicated applications, a font list may specify multiple font sets with each font set being tagged with a name; for example, Bold, Large, Small, and so on. The tags are to be associated with a tag of an XmString segment. A tag may be used to identify a specific font or fontset within a font list.

Font Set and Font List Syntax

Table 2-1 shows the syntax for a font set and font list.

Table 2-1 Font Set and Font List Syntax

Here are some examples of font resource specifications:

app_foo*fontList: -adobe-courier-medium-r-normal--24-240-75-75-m-\
150-*:

The preceding fontList specifies a fontset, consisting of one or more 24-point Adobe Courier fonts, as appropriate for the user's locale.

app_foo*fontList: -adobe-courier-medium-r-normal--18-*; *-gothic-\
*-18-*:

This fontList specifies a fontset consisting of an 18-point Courier font (if available) for some characters in the users data, and an 18-point Gothic font for the others.

Motif-based applications sometimes need direct access to the font set contained in a font list. For example, an application that uses a DrawingArea widget may want to label one of the images drawn there. The following sample code shows how to extract a font set from a font list. In this example, the tag XmFONTLIST_DEFAULT_TAG looks for the font set because this is the tag that says "codeset of the locale." Applications should use the tag XmFONTLIST_DEFAULT_TAG for any string that could contain localized data.

XFontSet FontList2FontSet( XmFontList fontlist)
{
XmFontContext context;
XmFontListEntry next_entry;
XmFontType type_return = XmFONT_IS_FONT;
char* font_tag;
XFontSet fontset;
XFontSet first_fontset;
Boolean have_font_set = False;

if ( !XmFontListInitFontContext(&context, fontlist)) {
     XtWarning("fl2fs: can't create fontlist context...");
     exit 0;
}

while ((next_entry = XmFontListNextEntry(context) != NULL) {

    fontset = (XFontSet) XmFontListEntryGetFont(next_entry, 
                &type_return);
    if (type_return == XmFONT_IS_FONTSET ) {

        font_tag = XmFontListEntryGetTag(next_entry);

        if (!strcmp(XmFONTLIST_DEFAULT_TAG, font_tag) {
            return fontset;
       }
        /* Remember the 1st fontset, just in case... */
        if (!have_font_set) {
            first_fontset = fontset;
            have_font_set = True;
       }
    }
}
if (have_font_set)
    return first_fontset;
return (XFontSet)NULL;
}

Font Functions

The following Xlib font management API functions are available:

  • XCreateFontSet()
  • XLocaleOfFontSet()
  • XFontsOfFontSet()
  • XBaseFontNameListOfFontSet()
  • XFreeFontSet()

The following Motif FontListAPI functions are available:

  • XmFontListEntryCreate()
  • XmFontListEntryAppend()
  • XmFontListEntryFree()
  • XmFontListEntryGetTag()
  • XmFontListEntryGetFont()
  • XmFontListEntryLoad()

Font Charsets

To improve basic interchange, fonts are organized according to the standard X-Consortium font charsets.

Default Font Set Per Language Group

Selecting base font names of a font set associated with a developer's language is usually easy because the developer is familiar with the language and the set of fonts needed.

Yet, when selecting the base font names of a font set for various locales, this task can be difficult because an XLFD font specification consists of 15 fields. For localized usage, the following fields are critical for selecting font sets:

  • FAMILY_NAME %F

  • WEIGHT_NAME %W

  • SLANT %S

  • ADD_STYLE %A

  • SPACING %SP

This simplifies the number of fields, yet the possible values for each of these fields may vary per locale. The actual point size (POINT_SIZE) may vary across platforms.

Throughout this documentation, the following convention should be used when specifying localized fonts:

-dt-%F-%W-%S-normal-%A-*-*-*-%SP-*

The following describes the minimum set of recommended values for each field to be used within the desktop for the critical fields when specifying font sets in resource (app-defaults) files.

Latin ISO8859-1 Fonts

FOUNDRY
`dt'

FAMILY_NAME
`interface user'
`interface system'
`application'

WEIGHT_NAME
medium or bold

SLANT
r or i

ADD_STYLE
sans or serif

SPACING
p or m

Other ISO8859 Fonts

The same values defined for ISO8859-1 are recommended.

JIS Japanese Font

FOUNDRY
`dt'

FAMILY_NAME
Gothic or Mincho

WEIGHT_NAME
medium or bold

SLANT
r

ADD_STYLE
*

SPACING
m

KSC Korean Font

FOUNDRY
`dt'

FAMILY_NAME
Totum or Pathang

WEIGHT_NAME
medium or bold

SLANT
r

ADD_STYLE
*

SPACING
m


Note: The FAMILY_NAME values may change depending on the official romanization of the two common font families in use. As background, Totum corresponds to fonts typically shipped as Gothic, Kodig, or Dotum; Pathang corresponds to fonts typically shipped as Myungo or Myeongjo.

CNS Traditional Chinese Font

FOUNDRY
`dt'

FAMILY_NAME
Sung and Kai

WEIGHT_NAME
medium or bold

SLANT
r

ADD_STYLE
*

SPACING
m

GB Simplified Chinese Font

FOUNDRY
`dt'

FAMILY_NAME
Song and Kai

WEIGHT_NAME
medium or bold

SLANT
r

ADD_STYLE
*

SPACING
m

Drawing Localized Text

There are several mechanisms provided to render a localized string, depending on the Motif or Xlib library being used. The following discusses the interfaces that are recommended for internationalized applications. Yet, it is recommended that all localized data be externalized from the program using the simple text.

Simple Text

The following Xlib multibyte (char*) drawing functions are available for internationalization:

The following Xlib wide character (wchar_t*) drawing functions are available for internationalization:

  • XwcDrawImageString()
  • XwcDrawString()
  • XwcDrawText()

The following Xlib multibyte (char*) font metric functions are available for internationalization:

  • XExtentsOfFontSet()
  • XmbTextEscapement()
  • XmbTextExtents()
  • XmbTextPerCharExtents

The following Xlib wide character (char_t*) font metric functions are available for internationalization:

  • XExtentsOfFontSet()
  • XwcTextEscapement()
  • XwcTextExtents()
  • XwcTextPerCharExtents

XmString (Compound String)

For the Xm library, localized text should be inserted into XmString segments using XmStringCreateLocalized(). The tag associated with localized text is XmFONTLIST_DEFAULT_TAG, which is used to match an entry in a font list. Applications that mix several fonts within a compound string using XmStringCreate() should use XmFONTLIST_DEFAULT_TAG as the tag for any localized string.

More importantly, for interclient communications, the XmStringConvertToCT() function associates a segment tagged as XmFONTLIST_DEFAULT_TAG as being encoded in the code set of the locale. Otherwise, depending on the tag name used, the Xm library may not be able to properly identify the encoding on interclient communications for text data.

A localized string segment inside an XmString can be drawn with a font list having a font set with XmFONTLIST_DEFAULT_TAG. Use of a localized string is recommended for portability.

The following is an example of creating a font list for drawing a localized string:

XmFontList CreateFontList( Display* dpy, char* pattern)
}

SmFontListEntry font_entry;
XmFontList fontlist;
font_entry = XmFontListEntryLoad( dpy, pattern,
                                       XmFONT_IS_FONTSET,
                                       XmFONTLIST_DEFAULT_TAG);

fontlist = XmFontListAppendEntry(NULL, font_entry);
/* XmFontListEntryFree(font_entry); */

if ( fontlist == NULL ) {
      XtWarning("fl2fs: can't create fontlist...");
      exit (0);
}

return fontlist;
}

int main(argc,argv)
int argc;
char **argv;
}
  Display *dpy;            /* Display                 */
  XtAppContext app_context;/*  Application Context    */

  XmFontList fontlist;
  XmFontSet fontset;
  XFontStruct** fontstructs;
  char** fontnames;
  int i,n;

char *progrname;     /* program name without the full pathname */

if (progname=strrchr(argv[0], `/')){
  progname++;
}
else  {
  progname = argv[0];
}

/*    Initialize toolkit and open display.
 */
XtSetLanguageProc(NULL, NULL, NULL);
XtToolkitInitialize():
app_context = XtCreateApplicationContext();
dpy = XtOpenDisplay(app_context, NULL, progname, "XMdemos",
                      NULL, 0, &argc, argv);
if (!dpy) {
    XtWarning("fl2fs: can't open display, exiting...");
    exit(0);
}

fontlist = CreateFontList(dpy, argv[1] );
fontset = FontList2FontSet( fontlist );

/*
 * Print out BaseFontNames of Fontset
 */
n = XFontsOfFontSet( fontset, &fontstructs, &fontnames);

  printf("Fonts for %s is %d\n", argv[1], n);

  for (i = 0 ; i < n ; ++i ) printf("font[%d} - %s\n", i,\
                                           fontnames[i] );

  exit(1);

}

A localized string can be written in resource files because a compound string specified in resource files has a locale-encoded segment with Xm_FONTLIST_DEFAULT_TAG. For example, the fontList resource in the following example is automatically associated with XmFONTLIST_DEFAULT_TAG.

labelString: Japanese string

*fontList:-dt-interface system-medium-r-normal-L*-*-*-*-*-*-*:

The following set of XmString functions is recommend for internationalization:

  • XmStringCreateLocalized()
  • XmStringDraw()
  • XmStringDrawImage()
  • XmStringDrawUnderline()

The following set of XmString functions is not recommend for internationalization because it takes a direction that may not work with languages not covered:

  • XmStringCreateLtoR()
  • XmStringSegementCreate()

Inputting Localized Text

Input for localized text is typically done by using either the local input method or the network-based input method.

The local input method means that the input method is built in the Xlib. It is typically used for a language that can be composed using simple rules and that does not require language-specific features. The network-based input method means that the actual input method is provided as separate servers, and Xlib communicates with them through the XIM protocol to do the language-specific composition.

Basic Prompts and Dialogs

It is strongly recommended that applications use the Text widget to do all text input.

Input within a DrawingArea Widget

Many applications do their own drawing within a widget based on input. To provide consistency within the desktop environment, XmIm functions are recommended because the style and geometry management needed for an input method is managed by the VendorShell widget class. The application need only worry about handling key events, focus, and communicating the current input location within the drawing area. Using these functions requires some basic knowledge of the underlying Xlib input method architecture, but a developer need only be concerned with the XmIm pieces of information.

Application-Specific and Language-Specific Intermediate Feedbacks

Some applications may need to directly display intermediate feedback during preediting, such as when an application exceeds the functions supplied by Xlib. Examples of this include for PostScript rendering or using vertical writing.

The core Xlib provides the common set of interfaces that allow an application to display intermediate feedback during preediting. By registering the application's callbacks and setting the preediting style to XNPreeditCallbacks, an application can get the intermediate preediting data from the input method and can draw whatever it needs.

Applications intended to do sophisticated language processing may recognize extensions within a specific XIM implementation and its input method engines. Such applications are on the leading edge and will require familiarity with details of the XIM functions.

Text and TextField Widget

For basic prompts and dialogs, the Text or TextField widget is recommended. Besides resources, all of the XmTextField and XmText functions are available for getting and for setting localized text inside a Text[Field] widget.

Most XmText functions are based on the number of characters, not on the number of bytes. For example, all XmTextPosition() function positions are character positions, not byte positions. The XmTextGetMaxLength() function returns the number of bytes. When in doubt, remember that positions are always in character units.

The width of a Text or TextField widget is determined by the resource value of XmNcolumns. But, this value means the number of the widest characters in the font set, not the number of bytes or columns. For example, suppose that you have selected a variable-width font for the Text widget. The character i may have a width of 1 pixel, while the character W may have a width of 7 pixels. When a value of 10 is set for XmNcolumns, this is considered a request to make the Text widget wide enough to be able to display at least 10 characters. So the Text widget must use the width of the widest character to determine the pixel width of its core widget. With this example, it may be able to display 10 W characters in the widget, or 70 i characters. This structure for XmNcolumns may cause problems in locales whose code set is a multibyte and a multicolumn encoding. As such, this value should be set within a localized resource.

The following section identifies the set of functions available for applications that are used to manage input methods. For applications that use the Text and TextField widgets, refer to "Input Method (Keyboards)".

Character Input within Customized Widgets Not Using Text[Field] Widgets

In some cases, an application may obtain character input from the user but does not use a TextField or Text widget to do so. For example, an application using a DrawingArea widget may allow the user to type in text directly into the DrawingArea. In this case, the application could use the Xlib XIM functions as described in later sections, or alternatively, the application may use the XmIm functions of Motif 1.2. The XmIm functions allow an application to connect to and interact with an input method with a minimum of code. Further, it allows the Motif VendorShell widget to take care of geometry management for the input method on the application's behalf.

Although the XmIm functions are shipped in all implementations of Motif 1.2, the functions are not documented in Motif 1.2. OSF has announced its intention to augment and document the XmIm functions for Motif 2.0. The functions described here are the Motif 1.2 XmIm functions.


Note: The Motif 1.2 XmIm functions do not support preedit callback style or status callback style input methods. The preedit callback can be used by the Xlib API. For more information, see "XIM Management".

Following are the XmIm functions you can safely use in a Motif 1.2-based application. The formal description of the parameters and types can be found in the Xm.h header file.

Function Name
Description

XmImRegister()
Performs XOpenIM() and queries the input method for supported styles.

XmImSetValues()
Negotiates and selects the preedit and status styles.

XmImSetFocusValues()
Creates the XIC, if one does not exist. Notifies the input method that the widget has gained the focus. Sets the values passed to the XIC.

XmImUnsetFocus()
Notifies the input method that the widget has lost the focus.

XmImMbLookupString()
Xm equivalent of XmbLookupString(); converts one or more key events into a character. Return value is identical to XmbLookupString().

XmImUnregister()
Disconnects the input method and the widget, allowing connection to a new input method. Does not necessarily close the input method (implementation-dependent).

The XmImSetValues() and XmImSetFocusValues() functions allow the application to pass information needed by the input method. It is important for the application to pass all values even though not all values are needed (for each supports preedit and status style). This is because the application can never be sure which style has been selected by the user or the VendorShell widget. Following are the arguments and data types of each value that should be passed in each call to the XmImSet[Focus]Values() function.

Argument Name
Data Type

XmNbackground
Pixel

XmNforeground
Pixel

XmNbackgroundPixmap
Pixmap

XmNspotLocation
XPoint

XmNfontList
Motif fontlist

XmNlineSpace
int (pixel height between consecutive baselines)

The XmIm functions are used in the following manner:

  • Before initializing the toolkit, the application should call XtSetLanguageProc(NULL, NULL, NULL) to initialize the locale.

  • After creating the widget where character input is desired, the application should call XmImRegister(widget) to open the input method and establish a connection.

  • After establishing a connection to the input method, the application should pass the initial XIC values to the input method by calling XmImSetValues() and passing all of the values listed above. This function takes an arg_list and a number_args argument. The arglist is loaded by calling XtSetArg().

  • Add an event handler, through the XtAddEventHandler() function, for the manager widget of the widget obtaining input from the input method. The event handler is for the FocusChangeMask mask. The handler should call XmImSetFocusValues() when gaining focus and should call XmImUnsetFocus() when losing focus. When setting focus for the input method, pass the full set of values listed above.

  • Add a DestroyCallback for the widget obtaining input from the input method. In the destroy callback, call XmImUnregister() to notify the input method that you are breaking the connection between the widget and the input method.

  • Use XmImSetValues() to notify the input method any time one or more of the input method values listed above change (for example, spotLocation).

XIM Management

Following are the XIM management functions.

Function Name
Description

XOpenIM()
Establishes a connection to an input method.

XCloseIM()
Removes a connection to an input method previously established with a call to XOpenIM().

XGetIMValues()
Queries the input method for a list of properties. Currently, the only standard argument in Xlib is XNQueryInputStyle.

XDisplayOfIM()
Returns the display associated with an input method.

XLocaleOfIM()
Returns a string identifying the locale of the input method. There are no standard strings; the value returned by this call is implementation-defined.

XCreateIC()
Creates an input context. The input context contains both the data required (if any) by an input method and the information required to display that data.

XDestroyIC()
Destroys an input context, freeing any associated memory.

XIMOfIC()
Returns the input method currently associated with a given input context.

XSetICValues()
Passes zero or more values to an input context to control input of character data, or control display of preedit or status information. A table of all valid input context value arguments can be found in the X11R5 specification.

XGetICValues()
Queries an input context to get zero or more input context values. A table of all valid input context value arguments can be found in the X11R5 specification.

XIM Event Handling

Following are the XIM event handling functions:

Function Name
Description

XmbLookupString()
Converts keypress events into characters.

XwcLookupString()
Converts keypress events into wide characters.

XmbResetIC()
Resets an input context to its initial state. Any input pending on that context is deleted. Returns the current preedit value as a char* string. Depending on the implementation of the input method, the return value may be NULL.

XwcResetIC()
Resets an input context to its initial state. Any input pending on that context is deleted. Returns the current preedit value as a wchar_t* string.

XFilterEvent()
Allows the input method to process any incoming events to the clients before the application processes them.

XSetICFocus()
Notifies the input method that the focus window attached to the specified input context has received keyboard focus.

XUnsetICFocus()
Notifies the input method that the specified input context has lost the keyboard focus and that no more input is expected on the focus window attached to that context.

XIM Callback

X Input Methods (XIMs) provide three categories of callbacks. One is preedit callbacks, which allow applications to display the intermediate feedbacks during preediting. The second is geometry callbacks, which allow applications and XIM to negotiate the geometry to be used for XIM. The third is status callbacks, which allow applications to display the internal status of XIM.

Table 2-2 XIM Callbacks

Extracting Localized Text

Although there are different methods to localize an application, the general rule is that any language-dependent information is outside the application and is stored in separate directories identified by a locale name.

This section describes how the user, the application developer, and the implementation combine to establish the language environment of the application. Two general approaches to localizing applications are also discussed. The following three methods can be used:

  • Resource files
  • Message catalogs
  • Private files

Resource Files

This is the GUI toolkit mechanism for customizing all sorts of information about an application. The Intrinsic library (libXt) provides a sophisticated mechanism for merging the command-line options, application-defined resources, and user-defined resources. Resource files can be used for extracting localized text. The difference between resource files and message catalogs is that the resource database is compiled each time it is loaded. As such, care should be taken when deciding which strings to place in resource files and which to place in message catalogs.

Also note that the Xm library functions do not depend on the LC_MESSAGE category when specifying the location from which localized resources are loaded. Refer to the XtSetLanguageProc() man page for more information.

Message Catalogs

This is the traditional operating system mechanism for accessing external databases containing localized text. These functions load a precompiled catalog file that is ready to be accessed. They also provide defaults within the actual program for cases when no catalogs may be found.

The messaging support is based on both the XPG4 and System V Release 4 (SVR4) interfaces for accessing message catalogs.

Private Files

Private databases can be used by applications to provide generic, customized databases for more than just localization text. Usually, such databases do contain text. It is recommended that if the database is to be spread out over many files, some run-time indirect access of localized text be provided. Without this access, localization for the average user is a difficult effort. Generally, such private file formats are discouraged by groups doing localization. But problems are reduced if a tool is provided specifically for localization of text only.

Message Guidelines

Message guidelines foster consistent formatting of message and help information. They also promote creation and maintenance of messages that can be easily understood by inexperienced English-speaking end users, as well as by inexperienced translators. Use these guidelines to create message files that are consistent in language and clear in meaning. Distribution of these guidelines enable programmers and writers to coordinate their message-writing efforts. Default messages, external message files, and planned delivery of translatable messages are required for each executable to fully implement international language support.

Message Extraction Functions

One of the requirements of internationalizing programs (basic commands and utilities inclusive) is that the messages displayed on the output devices be in the language of the user. As these programs may be used in many countries (international locales), the messages must be translated into the various languages of these countries.

There are two sets of message extraction functions in the desktop environment: XPG4 functions and Xlib functions.

XPG4/Universal UNIX Messaging Functions

The XPG4 message facility consists of several components: message source files, catalog generation facilities, and programming interfaces. Following are the XPG4/Universal UNIX message functions:

  • catopen()
  • catgets()
  • catclose()

XPG4 Messaging Examples

There are three parts to this example which demonstrates how to retrieve a message from a catalog. The first part shows the message source file and the second part shows the method used to generate the catalog file. The third part shows an example program using this catalog.

Message Source File
The message catalog can be specified as follows:

example.msg file:
$quote "
$ every message catalog should have a beginning set number.
$set 1 This is the set 1 of messages
1 "Hello world\n"
2 "Good Morning\n"
3 "example: 1000.220 Read permission is denied for the file
%s.\n"
$set 2
1 "Howdy\n"

Generation of Catalog File
This file is input to the gencat utility to generate the message catalog example.cat as follows:

gencat example example.msg

Accessing the Catalog in a Program
#include <locale.h>
#include <nl_types.h>
char *MF_EXAMPLE = "example.cat"

main()
{
        nl_catd catd;
        int error;

        (void)setlocale(LC_ALL, "");

        catd = catopen(MF_EXAMPLE, 0);
            /* Get the message number 1 from the first set.*/
        
        printf( catgets(catd,1,1,"Hello world\n") );
            /* Get the message number 1 from the second set.*/
        
        printf( catgets(catd, 2, 1,"Howdy\n") );
            /* Display an error message.*/
        
        printf( catgets(catd, 1, 4,"example: 100.220
            Permission is denied to read the file %s.\n") ,
            MF_EXAMPLE);
        catclose(catd);
}

Xlib Messaging Functions

The following Xlib messaging functions provide a similar input/output (I/O) operation to the resources.

  • XrmPutFileDatabase()
  • XrmGetFileDatabase()
  • XrmGetStringDatabase()
  • XrmLocaleOfDatabase()

They are described in X Window System, The Complete Reference to Xlib, Xprotocol, ICCCM, XLFD - X Version 11, Release 5.

Xlib Message and Resource Facilities

Part of internationalizing a system environment, toolkit-based application is not having any locale-specific data hardcoded within the application source. One common locale-specific item is messages (error and warning) returned by the application of the standard I/O.

In general, for any error or warning messages to be displayed to the user through a system environment toolkit widget or gadget, externalize the messages through message catalogs.

For dialog messages to be displayed through a toolkit component, externalize the messages through localized resource files. This is done in the same way as localizing resources, such as the XmLabel and XmPushButton classes' XmNlabelString resource or window titles.

For example, if a warning message is to be displayed through an XmMessageBox widget class, the XmNmessageString resource cannot be hardcoded within the application source code. Instead, the value of this resource must be retrieved from a message catalog. For an internationalized application expected to run in different locales, a distinct localized catalog must exist for each of the locales to be supported. In this way, the application need not be rebuilt.

Localized resource files can be put in the /usr/lib/X11/%L/appdefaults subdirectories, or they can be pointed to by the XENVIRONMENT environment variable. The %L variable is replaced with the name of the locale used at run time.

Localized Resources

This section describes which widget and gadget resources are locale-sensitive. The information is organized by related functionality. For example, the first section describes those resources that are locale-sensitive for widgets used to display labels or to provide push-button functionality.

Labels and Buttons

Table 2-3 lists the localized resources that are used as labels. Many of them are of type XmString. The rest are of type color or char*. See the Motif 1.2 Reference Manual for detailed descriptions of these resources. In each case, the application should not hardcode these resources. If resource values need to be specified by the application, it should be done with the app-defaults file, ensuring that the resource can be localized.

Only the widget class resources are listed here; subclasses of these widgets are not listed. For example, the XmDrawnButton widget class does not introduce any new resources that are localized. However, it is a subclass of the XmLabelWidget widget class; therefore, its accelerator resource, acceleratorText resource, and so on, are also localized and should not be hardcoded by an application.

Table 2-3 Localized Resources

Note that the XmRowColumn widget has additional string resources that may be localized. These resources are listed in the XmRowColumn man page, under the heading "Simple Menu Creation Resource Set." As the title implies, these resources affect only RowColumn widgets created with the XmCreateSimpleMenu() function. The resources affected are: *buttonAccelerators, *buttonAcceleratorText, *buttonMnemonics, *optionLabel, and *optionMnemonic. These resources are not included in Table 2-3 because they are rarely used and apply to RowColumn only when creating a simple menu.

List Resources

Several widgets allow applications to set or read lists of items in the widget. Table 2-4 shows which widgets allow this and the resources they use to set or read these lists. Because the list items may need to be localized, do not hardcode these lists. Rather, they should be set as resources in app-defaults files, allowing them to be localized. The type for each list is XmStringList.

Table 2-4 Resources Used for Reading Lists

Title

Table 2-5 lists the resources used for setting titles and icon names. Normally, an application need only set the *title: and *iconName: resources. The encoding of each is automatically detected for clients doing proper locale management. All of these are of type char or XmString.

Table 2-5 Resources Used for Setting Titles and Icon Names

Text Widget

Table 2-6 lists the Text[Field] resources that are locale-sensitive or about which the developer of an internationalized application should know.

Table 2-6 Locale-Sensitive Text[Field] Resources

Input Method (Keyboards)

Table 2-7 lists localized resources for customizing the input method. These resources allow the user or the application to control which input method will be used for the specified locale and which preedit style (if applicable and available) will be used.

Table 2-7 Localized Resources for Input Method Customization

Pixmap (Icon) Resources

Table 2-8 lists pixmap resources. In some cases, a different pixmap may be needed for a given locale.

Table 2-8 Pixmap Resources

A pixmap is a screen image that is stored in memory so that it can be recalled and displayed when needed. The desktop has a number of pixmap resources that allow the application to supply pixmaps for backgrounds, borders, shadows, label and button faces, drag icons, and other uses. As with text, some pixmaps may be specific to particular language environments; these pixmaps must be localized.

The desktop maintains caches of pixmaps and images. The XmGetPixmapByDepth() function searches these caches for a requested pixmap. If the requested pixmap is not in the pixmap cache and a corresponding image is not in the image cache, the XmGetPixmapByDepth() function searches for an X bitmap file whose name matches the requested image name. The XmGetPixmapByDepth() function calls the XtResolvePathname() function to search for the file. If the requested image name is an absolute path name, that path name is the search path for the XtResolvePathname() function. Otherwise, the XmGetPixmapByDepth() function constructs a search path in the following way:

  • If the XBMLANGPATH environment variable is set, the value of that variable is the search path.

  • If XBMLANGPATH is not set but XAPPLRESDIR is set, the XmGetPixmapByDepth() function uses a default search path with entries that include $XAPPLRESDIR, the user's home directory, and vendor-dependent system directories.

  • If neither XBMLANGPATH nor XAPPLRESDIR is set, the XmGetPixmapByDepth() function uses a default search path with entries that include the user's home directory and vendor-dependent system directories.

These paths may include the %B substitution field. In each call to the XtResolvePathname() function, the XmGetPixmapByDepth() function substitutes the requested image name for %B. The paths may also include other substitution fields accepted by the XtResolvePathname() function. In particular, the XtResolvePathname() function substitutes the display's language string for %L, and it substitutes the components of the display's language string (in a vendor-dependent way) for %l, %t, and %c. The substitution field %T is always mapped to bitmaps, and %S is always mapped to Null.

Because there is no string-to-pixmap converter supplied by default, pixmaps are generally set by the application at creation time by first retrieving the pixmap with a call to XmGetPixmap(). XmGetPixmap() uses the current locale to determine where to locate the pixmap. (See the XmGetPixmap() man page for a description of how locale is used to locate the pixmap.)

Font Resources

Table 2-9 lists the localized font resources. All XmFontList resources are of type XmFontList. In almost all cases, a fontset should be used when specifying a fontlist element. The only exception is when displaying character data that does not appear in the character set of the user (for example, displaying math symbols or dingbats).

Table 2-9 Localized Font Resources

Operating System Internationalized Functions

Table 2-10 lists the base operating system internationalized functions in a common open software environment.

Applications should perform proper locale management with the assumption that a locale may have from 1 to 4 bytes per coded character.

Table 2-10 Base Operating System Internationalized Functions

Table 2-10 Base Operating System Internationalized Functions (continued)