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. Followingare the XPG4/Universal UNIX^TM 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.