A locale is the language environment determined by the application at run time. The X/Open Portability Guide, Issue 3 (XPG3) defines locale as a means of specifying three characteristics of a language environment that might be required for localization:

· Language

· Territory

· Code set

These elements are represented by many systems in the following format:

<language>_<TERRITORY> . <code set> .

For example, ja_JP.ujis is the representation for Japanese, as used in Japan with the UJIS code set.

Using locales

At start-up, the application must find the correct UID file in either the DECW$USER_DEFAULTS or DECW$SYSTEM_DEFAULTS directories. See the DECwindows Motif Release Notes for more information.

As an example of using locales, assume you have an application with two different language versions. You set your XUSERFILESEARCHPATH (see Static output ) to the following (all of which should appear on one line):


This search path allows your application to search from the most specific designation of the locale to the least specific, allowing you a high degree of flexibility in configuring your application. See the explanation of "XtResolvePathname" in Vol. 5 of the O'Reilly & Assoc. X Toolkit Intrinsics Reference Manual for an explanation of the various substitutions and how they relate to the locale designation.

Most vendors' implementations of X automatically include locale-specific searches in the default search path environment variables, so setting these variables is usually unnecessary.


If you are using UIL for your application, you can use a similar mechanism to search for the compiled UIL (UID) files.

Set UIDPATH to the following (all of which should appear on one line):


At start-up, the application finds the correct UID file based on how your UIDPATH is set. See the description of MrmOpenHierarchy in the
OSF Motif 1.2 Programmer's Reference for further details.

Locales in Builder Xcessory

The application must have a way of recognizing the language environment in which it is running. Based on this information, the application can then make adjustments such as allowing the display of strings in the appropriate language. Builder Xcessory provides a code generation option to enable this support in your application.

Note: ViewKit applications always have localization support enabled by the VkApp object.

Enabling localization

To enable localization, follow these steps:

1. Select Code Generation Preferences from the Browser Options menu.

2. Click the Application tab on the Code Generation Preferences dialog ( Code Generation Preferences Dialog ).

3. Set the Initialize Localization Support toggle, and dismiss the dialog.

When the main C or C++ file is written, the following line is included:

(void) XtSetLanguageProc (NULL,

Builder Xcessory inserts code into the main routine to initialize the toolkit I18N features. When the code is compiled and run, the toolkit examines the LANG environment variable to determine the current locale, and then initialize its internal routines to deal with locale-specific issues.

For example, if the user has set the LANG environment variable to ja_JP . ujis , the application automatically initializes support for Japanese language character input and display, as well as monetary and date output, and so forth.


Code Generation Preferences Dialog

Setting locales

If the Initialize Localization Support toggle is not set, you can manually set the locale in your application using the ANSI C function setlocale . The function setlocale (LC_ALL,"") sets all locale-specific information to the default (the LANG environment variable). The function
setlocale(LC_COLLATE,"ja_JP.ujis") sets only the collation order to that of the Japanese UJIS code set.

The function setlocale() is called from the default language procedure installed by XtSetLanguageProc() , described in detail in Asente, Converse, Swick's X Window System Toolkit . XtSetLanguageProc() also initializes the toolkit internationalization techniques, connects to the input method (if necessary), and sets various defaults for the current locale, as specified by the LANG environment variable.

Note: The default language procedure can be replaced using XtSetLanguageProc() with arguments other than NULL. Refer to O'Reilly & Associates' X Window System , Volumes 4 and 5 for a more detailed discussion of Xt language procedures.

Locale-friendly coding

When coding an application to be run in multiple locales, consider the following issues:

· Use ANSI C or C++; Kernigan & Ritchie 1 implementations may not support locale-aware string manipulation.

· Use strcoll() rather than strcmp() for string comparisons.
strcmp() routine assumes an ASCII character set when doing string comparisons; strcoll() has no such limitation and can deal with locale-specific character encoding and sorting order.

· Do not make assumptions about word order in strings, and do not make comparisons to specific, hardcoded, characters.

· Use strftime() rather than ctime() or asctime().
formats time and dates according to locale; both ctime() and asctime() are of limited flexibility.

· Use ctype(3) library routines to identify character ranges.

· Use wchar_t , rather than char as the type for string processing.
The char type allocates a fixed size (8 or 16 bit, depending on the architecture) for a character. This is not enough to hold the characters of some locales, particularly the idiographic languages. The wchar_t type allocates size sufficient to hold the largest character in the current locale. This can be grossly inefficient, so you should only use wchar_t for operations that index arrays of characters.

· Do not hardcode decimal separators in parsing or arithmetic operations. Some languages use a comma rather than a period for a decimal separator.

· Do not embed pixmap graphics in code; specific colors and graphics can have different meanings from locale to locale.

Placing Resource Values in Resource or UIL Files

Your application should not explicitly code any language-dependent information. 2 This includes strings, fonts, and language-dependent pixmaps. In order to do this, the Open Group (formerly OSF) suggests that these resources be placed in message catalogs, resource files or UIL files.

Builder Xcessory allows resources to be placed in resource files. Once a resource is set, you can choose (on an individual resource or resource class basis) whether that resource is set in the code or in a resource file.

Individually, this choice is made with the Resource Placement menu, to the right of the text field used to enter the resource value (see Resource Editor Placement Settings ).


· Code indicates that the resource is hard-coded with calls to XtSetValues, and is the default.


· App indicates that the resource is placed in an app-defaults file, which can be edited to produce localized versions of the application.


Resource Editor Placement Settings

Resource values can also be placed in a resource file on a type basis by setting the resource's default resource placement. In the placement window, types can be specified to be put, by default, into Code or App (resource file).


For example, if you want to place all compound strings and fonts into resource files, follow these steps:

1. Select Default Resource Placement from the Resource Editor Options menu to display the Default Resource Type dialog:


Default Resource Type Dialog

2. Scroll the dialog to find the Compound String and Font types, and set the App toggle for each (see Default Resource Type Settings ).


Default Resource Type Settings

Generating Multiple UIL Files

Builder Xcessory also allows you to generate single or multiple UIL files, providing another language-independent way of specifying resource values that can be used to internationalize an application. To save resources in a UIL file, set the resource to be saved into code and when generating code, generate UIL instead of C or C++.

Note: You can only generate UIL files if generating an application in C (not in C++).

Once you generate a resource (or UIL) file, you must make copies of the file for each language supported and modify the contents accordingly. Then, using the locale of the machine and the environment variables LANG, UIDPATH, and XUSERFILESEARCHPATH, the different resource or UIL files are read and used by the application at run time.

For more information on this topic, refer to the OSF/Motif Programmer's Guide, Release 1.2, pages 11-26 to 11-31 and in the X Window System Toolkit, pages 433-436.

1. Kernigan, Brian & Ritchie, Dennis. The C Programming Language, 2nd ed. (Englewood Cliffs, NJ: Prentice Hall PTR, 1988).

2. OSF/Motif Programmer's Guide, Release 1.2, page 11-21; PTR Prentice Hall, Englewood Cliffs, New Jersey 07632