# gettext(3) - phpMan

[GETTEXT(3)]                 Library Functions Manual                 [GETTEXT(3)]



**NAME**
       gettext, dgettext, dcgettext - translate message

**SYNOPSIS**
       **#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**
       The  **gettext**,  **dgettext**  and **dcgettext** functions attempt to translate a
       text string into the user's native language, by looking up the transla-
       tion in a message catalog.

       The  _msgid_ argument identifies the message to be translated. By conven-
       tion, it is the English version of the message, with non-ASCII  charac-
       ters  replaced by ASCII approximations. This choice allows the transla-
       tors to work with message catalogs, called PO files, that contain  both
       the English and the translated versions of each message, and can be in-
       stalled using the **msgfmt** utility.

       A message domain is a set of translatable _msgid_ messages. Usually,  ev-
       ery  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  code-
       set  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  configura-
       tion  dependent;  typically  it is _prefix_/share/locale, where _prefix_ is
       the installation prefix of the package. _locale_ is the name of the  cur-
       rent  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  at-
       tempt 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  transla-
       tion  for  _msgid_,  the **gettext**, **dgettext** and **dcgettext** functions return
       _msgid_.

**RETURN** **VALUE**
       If a translation was found in one of the specified catalogs, it is con-
       verted  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**
       **errno** is not modified.

**BUGS**
       The  return type ought to be **const** **char** *****, but is **char** ***** to avoid warn-
       ings in C code predating ANSI C.

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

**SEE** **ALSO**
       [**ngettext**(3)],  [**dngettext**(3)], [**dcngettext**(3)], [**setlocale**(3)], [**textdomain**(3)],
       [**bindtextdomain**(3)], **bind**___**textdomain**___**[codeset**(3)], [**msgfmt**(1)]



GNU gettext 0.20.1.124-32cf        May 2001                         [GETTEXT(3)]