*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> gettext (3)              



NAME    [Toc]    [Back]

       gettext, dgettext, dcgettext - translate message

SYNOPSIS    [Toc]    [Back]

       #include <libintl.h>

       char * gettext (const char * msgid);
       char * dgettext (const char * domainname, const char * msgid);
       char * dcgettext (const char * domainname, const char * msgid,
			 int category);

DESCRIPTION    [Toc]    [Back]

       The  gettext,  dgettext	and dcgettext functions attempt to translate a
       text string into the user's native language, by looking up the translation
 in a message catalog.

       The  msgid argument identifies the message to be translated. By convention,
 it is the English version of the message, with non-ASCII  characters
  replaced by ASCII approximations. This choice allows the translators
 to work with message catalogs, called PO files, that contain  both
       the  English  and  the  translated versions of each message, and can be
       installed using the msgfmt utility.

       A message domain is a set  of  translatable  msgid  messages.  Usually,
       every  software	package has its own message domain. The domain name is
       used to determine the message catalog where the translation  is	looked
       up;  it	must  be  a  non-empty string. For the gettext function, it is
       specified through a preceding textdomain call.  For  the  dgettext  and
       dcgettext  functions,  it is passed as the domainname argument; if this
       argument is NULL, the domain name specified through a preceding textdo-
       main call is used instead.

       Translation  lookup  operates in the context of the current locale. For
       the gettext and dgettext functions, the	LC_MESSAGES  locale  facet  is
       used.  It  is determined by a preceding call to the setlocale function.
       setlocale(LC_ALL,"") initializes the LC_MESSAGES locale	based  on  the
       first nonempty value of the three environment variables LC_ALL, LC_MES-
       SAGES, LANG; see setlocale(3). For the dcgettext function,  the	locale
       facet  is  determined  by the category argument, which should be one of
       the LC_xxx  constants  defined  in  the	<locale.h>  header,  excluding
       LC_ALL. In both cases, the functions also use the LC_CTYPE locale facet
       in order to convert the translated message from the translator's  codeset
  to the current locale's codeset, unless overridden by a prior call
       to the bind_textdomain_codeset function.

       The  message  catalog  used  by	the  functions	is  at	the   pathname
       dirname/locale/category/domainname.mo.  Here  dirname  is the directory
       specified through bindtextdomain. Its default is system and  configuration
  dependent;  typically  it is prefix/share/locale, where prefix is
       the installation prefix of the package. locale is the name of the  current
  locale  facet; the GNU implementation also tries generalizations,
       such as the language name  without  the	territory  name.  category  is
       LC_MESSAGES  for  the  gettext  and dgettext functions, or the argument
       passed to the dcgettext function.

       If the LANGUAGE environment variable is set to a  nonempty  value,  and
       the  locale  is not the "C" locale, the value of LANGUAGE is assumed to
       contain a colon separated list of  locale  names.  The  functions  will
       attempt	to  look  up  a translation of msgid in each of the locales in
       turn. This is a GNU extension.

       In the "C" locale, or if none of the used catalogs contain  a  translation
  for  msgid,  the gettext, dgettext and dcgettext functions return

RETURN VALUE    [Toc]    [Back]

       If a translation was found in one of the specified catalogs, it is converted
  to  the	locale's codeset and returned. The resulting string is
       statically allocated and must not be modified or freed. Otherwise msgid
       is returned.

ERRORS    [Toc]    [Back]

       errno is not modified.

BUGS    [Toc]    [Back]

       The  return type ought to be const char *, but is char * to avoid warnings
 in C code predating ANSI C.

       When an empty string is used for msgid,	the  functions	may  return  a
       nonempty string.

SEE ALSO    [Toc]    [Back]

       ngettext(3),  dngettext(3), dcngettext(3), setlocale(3), textdomain(3),
       bindtextdomain(3), bind_textdomain_codeset(3), msgfmt(1)

GNU gettext 0.10.40		   May 2001			    GETTEXT(3)
[ Back ]
 Similar pages
Name OS Title
ngettext Linux translate message and choose plural form
st_strerror Tru64 translate a libst return code to a printable error message
gss_wrap HP-UX attach a message integrity code (MIC) to a message, and optionally encrypt the message content
gss_unwrap HP-UX verify a message with attached message integrity code (MIC) and decrypt message content if necessary
_toupper Tru64 Translate characters
tr OpenBSD translate characters
tr HP-UX translate characters
toupper Tru64 Translate characters
tolower Tru64 Translate characters
conv IRIX translate characters
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service