On Apache
Under GNU General Public License
2024-12-22 15:58 @3.15.138.214 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
File: libc.info, Node: Translation with gettext, Next: Locating gettext catalog, Up: Message catalogs with gettext
8.2.1.1 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)
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
AC-Unsafe corrupt lock fd mem | *Note 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 (*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)
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
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)
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
AC-Unsafe corrupt lock fd mem | *Note 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
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.
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-12-22 15:58 @3.15.138.214 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)