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 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).
char * gettext (const char *msgid) ¶Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.
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 although 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 (see How to determine which catalog to be used).
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 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.
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.
char * dgettext (const char *domainname, const char *msgid) ¶Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.
The dgettext function 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.
char * dcgettext (const char *domainname, const char *msgid, int category) ¶Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.
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 environment variable 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
than LC_MESSAGES 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 worthwhile 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.