GNU Info
(libc.info)Translation with gettext
What has to be done to translate a message?
...........................................
The `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 `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 `gettext' function is it 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 `catgets'.
The `gettext' approach has some advantages but also some
disadvantages. Please see the GNU `gettext' manual for a detailed
discussion of the pros and cons.
All the definitions and declarations for `gettext' can be found in
the `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
`libintl.a' (or accordingly different for shared libraries).
- Function: char * gettext (const char *MSGID)
The `gettext' function searches the currently selected message
catalogs for a string which is equal to MSGID. If there is such a
string available it is returned. Otherwise the argument string
MSGID is returned.
Please note that all though the return value is `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 (Note: Locating gettext catalog).
The `gettext' function does not modify the value of the global
ERRNO variable. This is necessary to make it possible to write
something like
printf (gettext ("Operation failed: %m\n"));
Here the ERRNO value is used in the `printf' function while
processing the `%m' format element and if the `gettext' function
would change this value (it is called before `printf' is called)
we would get a wrong message.
So there is no easy way to detect a missing message catalog beside
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 does
not need any translation.
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 `gettext' functions but since it must not depend on a
currently selected default message catalog it must specify all ambiguous
information.
- Function: char * dgettext (const char *DOMAINNAME, const char *MSGID)
The `dgettext' functions acts just like the `gettext' function.
It only takes an additional first argument DOMAINNAME which guides
the selection of the message catalogs which are searched for the
translation. If the DOMAINNAME parameter is the null pointer the
`dgettext' function is exactly equivalent to `gettext' since the
default value for the domain name is used.
As for `gettext' the return value type is `char *' which is an
anachronism. The returned string must never be modified.
- Function: char * dcgettext (const char *DOMAINNAME, const char
*MSGID, int CATEGORY)
The `dcgettext' adds another argument to those which `dgettext'
takes. This argument CATEGORY specifies the last piece of
information needed to localize the message catalog. I.e., the
domain name and the locale category exactly specify which message
catalog has to be used (relative to a given directory, see below).
The `dgettext' function can be expressed in terms of `dcgettext'
by using
dcgettext (domain, string, LC_MESSAGES)
instead of
dgettext (domain, string)
This also shows which values are expected for the third parameter.
One has to use the available selectors for the categories
available in `locale.h'. Normally the available values are
`LC_CTYPE', `LC_COLLATE', `LC_MESSAGES', `LC_MONETARY',
`LC_NUMERIC', and `LC_TIME'. Please note that `LC_ALL' must not
be used and even though the names might suggest this, there is no
relation to the environments variables of this name.
The `dcgettext' function is only implemented for compatibility with
other systems which have `gettext' functions. There is not really
any situation where it is necessary (or useful) to use a different
value but `LC_MESSAGES' in for the CATEGORY parameter. We are
dealing with messages here and any other choice can only be
irritating.
As for `gettext' the return value type is `char *' which is an
anachronism. The returned string must never be modified.
When using the three functions above in a program it is a frequent
case that the MSGID argument is a constant string. So it is worth to
optimize this case. Thinking shortly about this one will realize that
as long as no new message catalog is loaded the translation of a message
will not change. This optimization is actually implemented by the
`gettext', `dgettext' and `dcgettext' functions.
automatically generated by info2www version 1.2.2.9