@node Message Translation, Searching and Sorting, Locales, Top

@c %MENU% How to make the program speak the user's language

@chapter Message Translation

The program's interface with the user should be designed to ease the user's

task.  One way to ease the user's task is to use messages in whatever

language the user prefers.

Printing messages in different languages can be implemented in different

ways.  One could add all the different languages in the source code and

choose among the variants every time a message has to be printed.  This is

certainly not a good solution since extending the set of languages is

cumbersome (the code must be changed) and the code itself can become

really big with dozens of message sets.

A better solution is to keep the message sets for each language

in separate files which are loaded at runtime depending on the language

selection of the user.

@Theglibc{} provides two different sets of functions to support

message translation.  The problem is that neither of the interfaces is

officially defined by the POSIX standard.  The @code{catgets} family of

functions is defined in the X/Open standard but this is derived from

industry decisions and therefore not necessarily based on reasonable

decisions.

As mentioned above, the message catalog handling provides easy

extendability by using external data files which contain the message

translations.  I.e., these files contain for each of the messages used

in the program a translation for the appropriate language.  So the tasks

of the message handling functions are

@itemize @bullet

@item

locate the external data file with the appropriate translations

@item

load the data and make it possible to address the messages

@item

map a given key to the translated message

@end itemize

The two approaches mainly differ in the implementation of this last

step.  Decisions made in the last step influence the rest of the design.

@menu

* Message catalogs a la X/Open::  The @code{catgets} family of functions.

* The Uniforum approach::         The @code{gettext} family of functions.

@end menu

@node Message catalogs a la X/Open

@section X/Open Message Catalog Handling

The @code{catgets} functions are based on the simple scheme:

@quotation

Associate every message to translate in the source code with a unique

identifier.  To retrieve a message from a catalog file solely the

identifier is used.

@end quotation

This means for the author of the program that s/he will have to make

sure the meaning of the identifier in the program code and in the

message catalogs is always the same.

Before a message can be translated the catalog file must be located.

The user of the program must be able to guide the responsible function

to find whatever catalog the user wants.  This is separated from what

the programmer had in mind.

All the types, constants and functions for the @code{catgets} functions

are defined/declared in the @file{nl_types.h} header file.

@menu

* The catgets Functions::      The @code{catgets} function family.

* The message catalog files::  Format of the message catalog files.

* The gencat program::         How to generate message catalogs files which

                                can be used by the functions.

* Common Usage::               How to use the @code{catgets} interface.

@end menu

@node The catgets Functions

@subsection The @code{catgets} function family

@deftypefun nl_catd catopen (const char *@var{cat_name}, int @var{flag})

@standards{X/Open, nl_types.h}

@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}

@c catopen @mtsenv @ascuheap @acsmem

@c  strchr ok

@c  setlocale(,NULL) ok

@c  getenv @mtsenv

@c  strlen ok

@c  alloca ok

@c  stpcpy ok

@c  malloc @ascuheap @acsmem

@c  __open_catalog @ascuheap @acsmem

@c   strchr ok

@c   open_not_cancel_2 @acsfd

@c   strlen ok

@c   ENOUGH ok

@c    alloca ok

@c    memcpy ok

@c   fxstat64 ok

@c   __set_errno ok

@c   mmap @acsmem

@c   malloc dup @ascuheap @acsmem

@c   read_not_cancel ok

@c   free dup @ascuheap @acsmem

@c   munmap ok

@c   close_not_cancel_no_status ok

@c  free @ascuheap @acsmem

The @code{catopen} function tries to locate the message data file named

@var{cat_name} and loads it when found.  The return value is of an

opaque type and can be used in calls to the other functions to refer to

this loaded catalog.

The return value is @code{(nl_catd) -1} in case the function failed and

no catalog was loaded.  The global variable @var{errno} contains a code

for the error causing the failure.  But even if the function call

succeeded this does not mean that all messages can be translated.

Locating the catalog file must happen in a way which lets the user of

the program influence the decision.  It is up to the user to decide

about the language to use and sometimes it is useful to use alternate

catalog files.  All this can be specified by the user by setting some

environment variables.

The first problem is to find out where all the message catalogs are

stored.  Every program could have its own place to keep all the

different files but usually the catalog files are grouped by languages

and the catalogs for all programs are kept in the same place.

@cindex NLSPATH environment variable

To tell the @code{catopen} function where the catalog for the program

can be found the user can set the environment variable @code{NLSPATH} to

a value which describes her/his choice.  Since this value must be usable

for different languages and locales it cannot be a simple string.

Instead it is a format string (similar to @code{printf}'s).  An example

is

@smallexample

/usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N

@end smallexample

First one can see that more than one directory can be specified (with

the usual syntax of separating them by colons).  The next things to

observe are the format string, @code{%L} and @code{%N} in this case.

The @code{catopen} function knows about several of them and the

replacement for all of them is of course different.

@table @code

@item %N

This format element is substituted with the name of the catalog file.

This is the value of the @var{cat_name} argument given to

@code{catgets}.

@item %L

This format element is substituted with the name of the currently

selected locale for translating messages.  How this is determined is

explained below.

@item %l

(This is the lowercase ell.) This format element is substituted with the

language element of the locale name.  The string describing the selected

locale is expected to have the form

@code{@var{lang}[_@var{terr}[.@var{codeset}]]} and this format uses the

first part @var{lang}.

@item %t

This format element is substituted by the territory part @var{terr} of

the name of the currently selected locale.  See the explanation of the

format above.

@item %c

This format element is substituted by the codeset part @var{codeset} of

the name of the currently selected locale.  See the explanation of the

format above.

@item %%

Since @code{%} is used as a meta character there must be a way to

express the @code{%} character in the result itself.  Using @code{%%}

does this just like it works for @code{printf}.

@end table

Using @code{NLSPATH} allows arbitrary directories to be searched for

message catalogs while still allowing different languages to be used.

If the @code{NLSPATH} environment variable is not set, the default value

is

@smallexample

@var{prefix}/share/locale/%L/%N:@var{prefix}/share/locale/%L/LC_MESSAGES/%N

@end smallexample

@noindent

where @var{prefix} is given to @code{configure} while installing @theglibc{}

(this value is in many cases @code{/usr} or the empty string).

The remaining problem is to decide which must be used.  The value

decides about the substitution of the format elements mentioned above.

First of all the user can specify a path in the message catalog name

(i.e., the name contains a slash character).  In this situation the

@code{NLSPATH} environment variable is not used.  The catalog must exist

as specified in the program, perhaps relative to the current working

directory.  This situation in not desirable and catalogs names never

should be written this way.  Beside this, this behavior is not portable

to all other platforms providing the @code{catgets} interface.

@cindex LC_ALL environment variable

@cindex LC_MESSAGES environment variable

@cindex LANG environment variable

Otherwise the values of environment variables from the standard

environment are examined (@pxref{Standard Environment}).  Which

variables are examined is decided by the @var{flag} parameter of

@code{catopen}.  If the value is @code{NL_CAT_LOCALE} (which is defined

in @file{nl_types.h}) then the @code{catopen} function uses the name of

the locale currently selected for the @code{LC_MESSAGES} category.

If @var{flag} is zero the @code{LANG} environment variable is examined.

This is a left-over from the early days when the concept of locales

had not even reached the level of POSIX locales.

The environment variable and the locale name should have a value of the

form @code{@var{lang}[_@var{terr}[.@var{codeset}]]} as explained above.

If no environment variable is set the @code{"C"} locale is used which

prevents any translation.

The return value of the function is in any case a valid string.  Either

it is a translation from a message catalog or it is the same as the

@var{string} parameter.  So a piece of code to decide whether a

translation actually happened must look like this:

@smallexample

@{

  char *trans = catgets (desc, set, msg, input_string);

  if (trans == input_string)

    @{

      /* Something went wrong.  */

    @}

@}

@end smallexample

@noindent

When an error occurs the global variable @var{errno} is set to

@table @var

@item EBADF

The catalog does not exist.

@item ENOMSG

The set/message tuple does not name an existing element in the

message catalog.

@end table

While it sometimes can be useful to test for errors programs normally

will avoid any test.  If the translation is not available it is no big

problem if the original, untranslated message is printed.  Either the

user understands this as well or s/he will look for the reason why the

messages are not translated.

@end deftypefun

Please note that the currently selected locale does not depend on a call

to the @code{setlocale} function.  It is not necessary that the locale

data files for this locale exist and calling @code{setlocale} succeeds.

The @code{catopen} function directly reads the values of the environment

variables.

@deftypefun {char *} catgets (nl_catd @var{catalog_desc}, int @var{set}, int @var{message}, const char *@var{string})

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The function @code{catgets} has to be used to access the message catalog

previously opened using the @code{catopen} function.  The

@var{catalog_desc} parameter must be a value previously returned by

@code{catopen}.

The next two parameters, @var{set} and @var{message}, reflect the

internal organization of the message catalog files.  This will be

explained in detail below.  For now it is interesting to know that a

catalog can consist of several sets and the messages in each thread are

individually numbered using numbers.  Neither the set number nor the

message number must be consecutive.  They can be arbitrarily chosen.

But each message (unless equal to another one) must have its own unique

pair of set and message numbers.

Since it is not guaranteed that the message catalog for the language

selected by the user exists the last parameter @var{string} helps to

handle this case gracefully.  If no matching string can be found

@var{string} is returned.  This means for the programmer that

@itemize @bullet

@item

the @var{string} parameters should contain reasonable text (this also

helps to understand the program seems otherwise there would be no hint

on the string which is expected to be returned.

@item

all @var{string} arguments should be written in the same language.

@end itemize

@end deftypefun

It is somewhat uncomfortable to write a program using the @code{catgets}

functions if no supporting functionality is available.  Since each

set/message number tuple must be unique the programmer must keep lists

of the messages at the same time the code is written.  And the work

between several people working on the same project must be coordinated.

We will see how some of these problems can be relaxed a bit (@pxref{Common

Usage}).

@deftypefun int catclose (nl_catd @var{catalog_desc})

@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}

@c catclose @ascuheap @acucorrupt @acsmem

@c  __set_errno ok

@c  munmap ok

@c  free @ascuheap @acsmem

The @code{catclose} function can be used to free the resources

associated with a message catalog which previously was opened by a call

to @code{catopen}.  If the resources can be successfully freed the

function returns @code{0}.  Otherwise it returns @code{@minus{}1} and the

global variable @var{errno} is set.  Errors can occur if the catalog

descriptor @var{catalog_desc} is not valid in which case @var{errno} is

set to @code{EBADF}.

@end deftypefun

@node The message catalog files

@subsection  Format of the message catalog files

The only reasonable way to translate all the messages of a function and

store the result in a message catalog file which can be read by the

@code{catopen} function is to write all the message text to the

translator and let her/him translate them all.  I.e., we must have a

file with entries which associate the set/message tuple with a specific

translation.  This file format is specified in the X/Open standard and

is as follows:

@itemize @bullet

@item

Lines containing only whitespace characters or empty lines are ignored.

@item

Lines which contain as the first non-whitespace character a @code{$}

followed by a whitespace character are comment and are also ignored.

@item

If a line contains as the first non-whitespace characters the sequence

@code{$set} followed by a whitespace character an additional argument

is required to follow.  This argument can either be:

@itemize @minus

@item

a number.  In this case the value of this number determines the set

to which the following messages are added.

@item

an identifier consisting of alphanumeric characters plus the underscore

character.  In this case the set get automatically a number assigned.

This value is one added to the largest set number which so far appeared.

How to use the symbolic names is explained in section @ref{Common Usage}.

It is an error if a symbol name appears more than once.  All following

messages are placed in a set with this number.

@end itemize

@item

If a line contains as the first non-whitespace characters the sequence

@code{$delset} followed by a whitespace character an additional argument

is required to follow.  This argument can either be:

@itemize @minus

@item

a number.  In this case the value of this number determines the set

which will be deleted.

@item

an identifier consisting of alphanumeric characters plus the underscore

character.  This symbolic identifier must match a name for a set which

previously was defined.  It is an error if the name is unknown.

@end itemize

In both cases all messages in the specified set will be removed.  They

will not appear in the output.  But if this set is later again selected

with a @code{$set} command again messages could be added and these

messages will appear in the output.

@item

If a line contains after leading whitespaces the sequence

@code{$quote}, the quoting character used for this input file is

changed to the first non-whitespace character following

@code{$quote}.  If no non-whitespace character is present before the

line ends quoting is disabled.

By default no quoting character is used.  In this mode strings are

terminated with the first unescaped line break.  If there is a

@code{$quote} sequence present newline need not be escaped.  Instead a

string is terminated with the first unescaped appearance of the quote

character.

A common usage of this feature would be to set the quote character to

@code{"}.  Then any appearance of the @code{"} in the strings must

be escaped using the backslash (i.e., @code{\"} must be written).

@item

Any other line must start with a number or an alphanumeric identifier

(with the underscore character included).  The following characters

(starting after the first whitespace character) will form the string

which gets associated with the currently selected set and the message

number represented by the number and identifier respectively.

If the start of the line is a number the message number is obvious.  It

is an error if the same message number already appeared for this set.

If the leading token was an identifier the message number gets

automatically assigned.  The value is the current maximum message

number for this set plus one.  It is an error if the identifier was

already used for a message in this set.  It is OK to reuse the

identifier for a message in another thread.  How to use the symbolic

identifiers will be explained below (@pxref{Common Usage}).  There is

one limitation with the identifier: it must not be @code{Set}.  The

reason will be explained below.

The text of the messages can contain escape characters.  The usual bunch

of characters known from the @w{ISO C} language are recognized

(@code{\n}, @code{\t}, @code{\v}, @code{\b}, @code{\r}, @code{\f},

@code{\\}, and @code{\@var{nnn}}, where @var{nnn} is the octal coding of

a character code).

@end itemize

@strong{Important:} The handling of identifiers instead of numbers for

the set and messages is a GNU extension.  Systems strictly following the

X/Open specification do not have this feature.  An example for a message

catalog file is this:

@smallexample

$ This is a leading comment.

$quote "

$set SetOne

1 Message with ID 1.

two "   Message with ID \"two\", which gets the value 2 assigned"

$set SetTwo

$ Since the last set got the number 1 assigned this set has number 2.

4000 "The numbers can be arbitrary, they need not start at one."

@end smallexample

This small example shows various aspects:

@itemize @bullet

@item

Lines 1 and 9 are comments since they start with @code{$} followed by

a whitespace.

@item

The quoting character is set to @code{"}.  Otherwise the quotes in the

message definition would have to be omitted and in this case the

message with the identifier @code{two} would lose its leading whitespace.

@item

Mixing numbered messages with messages having symbolic names is no

problem and the numbering happens automatically.

@end itemize

While this file format is pretty easy it is not the best possible for

use in a running program.  The @code{catopen} function would have to

parse the file and handle syntactic errors gracefully.  This is not so

easy and the whole process is pretty slow.  Therefore the @code{catgets}

functions expect the data in another more compact and ready-to-use file

format.  There is a special program @code{gencat} which is explained in

detail in the next section.

Files in this other format are not human readable.  To be easy to use by

programs it is a binary file.  But the format is byte order independent

so translation files can be shared by systems of arbitrary architecture

(as long as they use @theglibc{}).

Details about the binary file format are not important to know since

these files are always created by the @code{gencat} program.  The

sources of @theglibc{} also provide the sources for the

@code{gencat} program and so the interested reader can look through

these source files to learn about the file format.

@node The gencat program

@subsection Generate Message Catalogs files

@cindex gencat

The @code{gencat} program is specified in the X/Open standard and the

GNU implementation follows this specification and so processes

all correctly formed input files.  Additionally some extension are

implemented which help to work in a more reasonable way with the

@code{catgets} functions.

The @code{gencat} program can be invoked in two ways:

@example

`gencat [@var{Option} @dots{}] [@var{Output-File} [@var{Input-File} @dots{}]]`

@end example

This is the interface defined in the X/Open standard.  If no

@var{Input-File} parameter is given, input will be read from standard

input.  Multiple input files will be read as if they were concatenated.

If @var{Output-File} is also missing, the output will be written to

standard output.  To provide the interface one is used to from other

programs a second interface is provided.

@smallexample

`gencat [@var{Option} @dots{}] -o @var{Output-File} [@var{Input-File} @dots{}]`

@end smallexample

The option @samp{-o} is used to specify the output file and all file

arguments are used as input files.

Beside this one can use @file{-} or @file{/dev/stdin} for

@var{Input-File} to denote the standard input.  Corresponding one can

use @file{-} and @file{/dev/stdout} for @var{Output-File} to denote

standard output.  Using @file{-} as a file name is allowed in X/Open

while using the device names is a GNU extension.

The @code{gencat} program works by concatenating all input files and

then @strong{merging} the resulting collection of message sets with a

possibly existing output file.  This is done by removing all messages

with set/message number tuples matching any of the generated messages

from the output file and then adding all the new messages.  To

regenerate a catalog file while ignoring the old contents therefore

requires removing the output file if it exists.  If the output is

written to standard output no merging takes place.

@noindent

The following table shows the options understood by the @code{gencat}

program.  The X/Open standard does not specify any options for the

program so all of these are GNU extensions.

@table @samp

@item -V

@itemx --version

Print the version information and exit.

@item -h

@itemx --help

Print a usage message listing all available options, then exit successfully.

@item --new

Do not merge the new messages from the input files with the old content

of the output file.  The old content of the output file is discarded.

@item -H

@itemx --header=name

This option is used to emit the symbolic names given to sets and

messages in the input files for use in the program.  Details about how

to use this are given in the next section.  The @var{name} parameter to

this option specifies the name of the output file.  It will contain a

number of C preprocessor @code{#define}s to associate a name with a

number.

Please note that the generated file only contains the symbols from the

input files.  If the output is merged with the previous content of the

output file the possibly existing symbols from the file(s) which

generated the old output files are not in the generated header file.

@end table

@node Common Usage

@subsection How to use the @code{catgets} interface

The @code{catgets} functions can be used in two different ways.  By

following slavishly the X/Open specs and not relying on the extension

and by using the GNU extensions.  We will take a look at the former

method first to understand the benefits of extensions.

@subsubsection Not using symbolic names

Since the X/Open format of the message catalog files does not allow

symbol names we have to work with numbers all the time.  When we start

writing a program we have to replace all appearances of translatable

strings with something like

@smallexample

catgets (catdesc, set, msg, "string")

@end smallexample

@noindent

@var{catgets} is retrieved from a call to @code{catopen} which is

normally done once at the program start.  The @code{"string"} is the

string we want to translate.  The problems start with the set and

message numbers.

In a bigger program several programmers usually work at the same time on

the program and so coordinating the number allocation is crucial.

Though no two different strings must be indexed by the same tuple of

numbers it is highly desirable to reuse the numbers for equal strings

with equal translations (please note that there might be strings which

are equal in one language but have different translations due to

difference contexts).

The allocation process can be relaxed a bit by different set numbers for

different parts of the program.  So the number of developers who have to

coordinate the allocation can be reduced.  But still lists must be keep

track of the allocation and errors can easily happen.  These errors

cannot be discovered by the compiler or the @code{catgets} functions.

Only the user of the program might see wrong messages printed.  In the

worst cases the messages are so irritating that they cannot be

recognized as wrong.  Think about the translations for @code{"true"} and

@code{"false"} being exchanged.  This could result in a disaster.

@subsubsection Using symbolic names

The problems mentioned in the last section derive from the fact that:

@enumerate

@item

the numbers are allocated once and due to the possibly frequent use of

them it is difficult to change a number later.

@item

the numbers do not allow guessing anything about the string and

therefore collisions can easily happen.

@end enumerate

By constantly using symbolic names and by providing a method which maps

the string content to a symbolic name (however this will happen) one can

prevent both problems above.  The cost of this is that the programmer

has to write a complete message catalog file while s/he is writing the

program itself.

This is necessary since the symbolic names must be mapped to numbers

before the program sources can be compiled.  In the last section it was

described how to generate a header containing the mapping of the names.

E.g., for the example message file given in the last section we could

call the @code{gencat} program as follows (assume @file{ex.msg} contains

the sources).

@smallexample

gencat -H ex.h -o ex.cat ex.msg

@end smallexample

@noindent

This generates a header file with the following content:

@smallexample

#define SetTwoSet 0x2   /* ex.msg:8 */

#define SetOneSet 0x1   /* ex.msg:4 */

#define SetOnetwo 0x2   /* ex.msg:6 */

@end smallexample

As can be seen the various symbols given in the source file are mangled

to generate unique identifiers and these identifiers get numbers

assigned.  Reading the source file and knowing about the rules will

allow to predict the content of the header file (it is deterministic)

but this is not necessary.  The @code{gencat} program can take care for

everything.  All the programmer has to do is to put the generated header

file in the dependency list of the source files of her/his project and

add a rule to regenerate the header if any of the input files change.

One word about the symbol mangling.  Every symbol consists of two parts:

the name of the message set plus the name of the message or the special

string @code{Set}.  So @code{SetOnetwo} means this macro can be used to

access the translation with identifier @code{two} in the message set

@code{SetOne}.

The other names denote the names of the message sets.  The special

string @code{Set} is used in the place of the message identifier.

If in the code the second string of the set @code{SetOne} is used the C

code should look like this:

@smallexample

catgets (catdesc, SetOneSet, SetOnetwo,

         "   Message with ID \"two\", which gets the value 2 assigned")

@end smallexample

Writing the function this way will allow to change the message number

and even the set number without requiring any change in the C source

code.  (The text of the string is normally not the same; this is only

for this example.)

@subsubsection How does to this allow to develop

To illustrate the usual way to work with the symbolic version numbers

here is a little example.  Assume we want to write the very complex and

famous greeting program.  We start by writing the code as usual:

@smallexample

#include <stdio.h>

int

main (void)

@{

  printf ("Hello, world!\n");

  return 0;

@}

@end smallexample

Now we want to internationalize the message and therefore replace the

message with whatever the user wants.

@smallexample

#include <nl_types.h>

#include <stdio.h>

#include "msgnrs.h"

int

main (void)

@{

  nl_catd catdesc = catopen ("hello.cat", NL_CAT_LOCALE);

  printf (catgets (catdesc, SetMainSet, SetMainHello,

                   "Hello, world!\n"));

  catclose (catdesc);

  return 0;

@}

@end smallexample

We see how the catalog object is opened and the returned descriptor used

in the other function calls.  It is not really necessary to check for

failure of any of the functions since even in these situations the

functions will behave reasonable.  They simply will be return a

translation.

What remains unspecified here are the constants @code{SetMainSet} and

@code{SetMainHello}.  These are the symbolic names describing the

message.  To get the actual definitions which match the information in

the catalog file we have to create the message catalog source file and

process it using the @code{gencat} program.

@smallexample

$ Messages for the famous greeting program.

$quote "

$set Main

Hello "Hallo, Welt!\n"

@end smallexample

Now we can start building the program (assume the message catalog source

file is named @file{hello.msg} and the program source file @file{hello.c}):

@smallexample

% gencat -H msgnrs.h -o hello.cat hello.msg

% cat msgnrs.h

#define MainSet 0x1     /* hello.msg:4 */

#define MainHello 0x1   /* hello.msg:5 */

% gcc -o hello hello.c -I.

% cp hello.cat /usr/share/locale/de/LC_MESSAGES

% echo $LC_ALL

de

% ./hello

Hallo, Welt!

%

@end smallexample

The call of the @code{gencat} program creates the missing header file

@file{msgnrs.h} as well as the message catalog binary.  The former is

used in the compilation of @file{hello.c} while the later is placed in a

directory in which the @code{catopen} function will try to locate it.

Please check the @code{LC_ALL} environment variable and the default path

for @code{catopen} presented in the description above.

@node The Uniforum approach

@section The Uniforum approach to Message Translation

Sun Microsystems tried to standardize a different approach to message

translation in the Uniforum group.  There never was a real standard

defined but still the interface was used in Sun's operating systems.

Since this approach fits better in the development process of free

software it is also used throughout the GNU project and the GNU

@file{gettext} package provides support for this outside @theglibc{}.

The code of the @file{libintl} from GNU @file{gettext} is the same as

the code in @theglibc{}.  So the documentation in the GNU

@file{gettext} manual is also valid for the functionality here.  The

following text will describe the library functions in detail.  But the

numerous helper programs are not described in this manual.  Instead

people should read the GNU @file{gettext} manual

(@pxref{Top,,GNU gettext utilities,gettext,Native Language Support Library and Tools}).

We will only give a short overview.

Though the @code{catgets} functions are available by default on more

systems the @code{gettext} interface is at least as portable as the

former.  The GNU @file{gettext} package can be used wherever the

functions are not available.

@menu

* Message catalogs with gettext::  The @code{gettext} family of functions.

* Helper programs for gettext::    Programs to handle message catalogs

                                    for @code{gettext}.

@end menu

@node Message catalogs with gettext

@subsection The @code{gettext} family of functions

The paradigms underlying the @code{gettext} approach to message

translations is different from that of the @code{catgets} functions the

basic functionally is equivalent.  There are functions of the following

categories:

@menu

* Translation with gettext::       What has to be done to translate a message.

* Locating gettext catalog::       How to determine which catalog to be used.

* Advanced gettext functions::     Additional functions for more complicated

                                    situations.

* Charset conversion in gettext::  How to specify the output character set

                                    @code{gettext} uses.

* GUI program problems::           How to use @code{gettext} in GUI programs.

* Using gettextized software::     The possibilities of the user to influence

                                    the way @code{gettext} works.

@end menu

@node Translation with gettext

@subsubsection What has to be done to translate a message?

The @code{gettext} functions have a very simple interface.  The most

basic function just takes the string which shall be translated as the

argument and it returns the translation.  This is fundamentally

different from the @code{catgets} approach where an extra key is

necessary and the original string is only used for the error case.

If the string which has to be translated is the only argument this of

course means the string itself is the key.  I.e., the translation will

be selected based on the original string.  The message catalogs must

therefore contain the original strings plus one translation for any such

string.  The task of the @code{gettext} function is to compare the

argument string with the available strings in the catalog and return the

appropriate translation.  Of course this process is optimized so that

this process is not more expensive than an access using an atomic key

like in @code{catgets}.

The @code{gettext} approach has some advantages but also some

disadvantages.  Please see the GNU @file{gettext} manual for a detailed

discussion of the pros and cons.

All the definitions and declarations for @code{gettext} can be found in

the @file{libintl.h} header file.  On systems where these functions are

not part of the C library they can be found in a separate library named

@file{libintl.a} (or accordingly different for shared libraries).

@deftypefun {char *} gettext (const char *@var{msgid})

@standards{GNU, libintl.h}

@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}

@c Wrapper for dcgettext.

The @code{gettext} function searches the currently selected message

catalogs for a string which is equal to @var{msgid}.  If there is such a

string available it is returned.  Otherwise the argument string

@var{msgid} is returned.

Please note that although the return value is @code{char *} the

returned string must not be changed.  This broken type results from the

history of the function and does not reflect the way the function should

be used.

Please note that above we wrote ``message catalogs'' (plural).  This is

a specialty of the GNU implementation of these functions and we will

say more about this when we talk about the ways message catalogs are

selected (@pxref{Locating gettext catalog}).

The @code{gettext} function does not modify the value of the global

@var{errno} variable.  This is necessary to make it possible to write

something like

@smallexample

  printf (gettext ("Operation failed: %m\n"));

@end smallexample

Here the @var{errno} value is used in the @code{printf} function while

processing the @code{%m} format element and if the @code{gettext}

function would change this value (it is called before @code{printf} is

called) we would get a wrong message.

So there is no easy way to detect a missing message catalog besides

comparing the argument string with the result.  But it is normally the

task of the user to react on missing catalogs.  The program cannot guess

when a message catalog is really necessary since for a user who speaks

the language the program was developed in, the message does not need any translation.

@end deftypefun

The remaining two functions to access the message catalog add some

functionality to select a message catalog which is not the default one.

This is important if parts of the program are developed independently.

Every part can have its own message catalog and all of them can be used

at the same time.  The C library itself is an example: internally it

uses the @code{gettext} functions but since it must not depend on a

currently selected default message catalog it must specify all ambiguous

information.

@deftypefun {char *} dgettext (const char *@var{domainname}, const char *@var{msgid})