XPRNLS library

Topics covered in this chapter:

General

The XPRNLS library must be initialized with a call to XNLSinit before being used. This initialization function may be called several times and each call must be matched with a call to XNLSfinish after terminating the use of the library.

All encoding conversion routines expect an encoding ID to identify an encoding. This numerical identifier is obtained from an encoding name via XNLSgetencid.

Handling of program parameters

In addition to transcoding routines the library also provides an operating system independent method for retrieving program parameters (namely argc and argv of the main function of the C program) encoded as UTF-8. The procedure requires the main program to be named XNLS_MAIN and the argv parameter to be of type XNLSargv. The function XNLSconvargv can then be called to get the converted arguments. The following example shows how to organise the main function of a program using this feature:

int XNLS_MAIN(int argc,XNLSargv sargv[])
{
 char **argv;

 argv=XNLSconvargv(&argc,sargv);   /* 'argv' is encoded in UTF-8 */

 /* Insert here the body of the function using 'argc' and 'argv' as usual */

 XNLSfreeargv(argv);
 return 0;
}

Buffer and string encoding conversion

The functions in this section serve for converting character strings from and to UTF-8 encoding. The functions XNLSconvstrfrom and XNLSconvbuffrom return a statically allocated buffer (that is re-used each time any of these functions is called) while XNLSconvbuffrom and XNLSconvbufto require a destination buffer.

Stream encoding conversion

These functions are designed for the transcoding of text streams. The creation of a stream with XNLSopenconv requires an additional function used to read (or write for an output stream) a block of data: it is called whenever the internal buffer of the transcoder is empty (or full if writing). When the stream is open for reading the user calls iteratively the reader routine XNLSconvread to get the data of the stream encoded in UTF-8. If the stream is open for writing the data sent to XNLSconvwrite is expected to be encoded in UTF-8 and it is transcoded to the encoding specified at the creation of the stream.

Translation

The library publishes an implementation of the so-called gettext system for automatic translation of text strings in a program. This system relies on message catalog files containing for each message of the application both the English version and its translation in a particular language (there is therefore one message catalog file per language and application). The message catalog files are organised in a dedicated directory hierarchy: the root directory of the localisation data (usually named locale) contains one sub-directory per language named after its ISO 639 code (for instance de for German, it for Italian etc). The message catalogs for a given language are stored under the LC_MESSAGES sub-directory of this language specific directory. Each message catalog file has the name of the domain it provides translations for (typically the name of the application) with the extension .mo (Machine Object). An mo file is generated using the command xprnls mogen (see Section XPRNLS Command line tool) from a po file (Portable Object).

A program using the XPRNLS translation framework must first open the domain for which it needs translations using XNLSopenmsgdom in order to get a domain descriptor. Then each message translation can be obtained by applying XNLSgettext to the English version of the text: the translated message is returned if the message catalog file for the current language has been found and includes the translation. Otherwise the original English text is used as the return value.