GETTEXT(3)             FreeBSD 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 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 textdomain 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_MESSAGES,
     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 msgid.

RETURN VALUE

     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

     errno is not modified.

BUGS

     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

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

GNU gettext 1.0                  November 2024                      GETTEXT(3)