gettext, jpayne@68: dgettext, dcgettext - translate message
jpayne@68: jpayne@68:#include jpayne@68: <libintl.h>
jpayne@68: jpayne@68:char *
jpayne@68: gettext (const char * msgid);
jpayne@68: char * dgettext (const char * domainname,
jpayne@68: const char * msgid);
jpayne@68: char * dcgettext (const char * domainname,
jpayne@68: const char * msgid,
jpayne@68: int category);
The jpayne@68: gettext, dgettext and dcgettext jpayne@68: functions attempt to translate a text string into the jpayne@68: user’s native language, by looking up the translation jpayne@68: in a message catalog.
jpayne@68: jpayne@68:The jpayne@68: msgid argument identifies the message to be jpayne@68: translated. By convention, it is the English version of the jpayne@68: message, with non-ASCII characters replaced by ASCII jpayne@68: approximations. This choice allows the translators to work jpayne@68: with message catalogs, called PO files, that contain both jpayne@68: the English and the translated versions of each message, and jpayne@68: can be installed using the msgfmt utility.
jpayne@68: jpayne@68:A message jpayne@68: domain is a set of translatable msgid messages. jpayne@68: Usually, every software package has its own message domain. jpayne@68: The domain name is used to determine the message catalog jpayne@68: where the translation is looked up; it must be a non-empty jpayne@68: string. For the gettext function, it is specified jpayne@68: through a preceding textdomain call. For the jpayne@68: dgettext and dcgettext functions, it is passed jpayne@68: as the domainname argument; if this argument is NULL, jpayne@68: the domain name specified through a preceding jpayne@68: textdomain call is used instead.
jpayne@68: jpayne@68:Translation jpayne@68: lookup operates in the context of the current locale. For jpayne@68: the gettext and dgettext functions, the jpayne@68: LC_MESSAGES locale facet is used. It is determined by jpayne@68: a preceding call to the setlocale function. jpayne@68: setlocale(LC_ALL,"") initializes the jpayne@68: LC_MESSAGES locale based on the first nonempty value jpayne@68: of the three environment variables LC_ALL, jpayne@68: LC_MESSAGES, LANG; see setlocale(3). jpayne@68: For the dcgettext function, the locale facet is jpayne@68: determined by the category argument, which should be jpayne@68: one of the LC_xxx constants defined in the jpayne@68: <locale.h> header, excluding LC_ALL. In both jpayne@68: cases, the functions also use the LC_CTYPE locale jpayne@68: facet in order to convert the translated message from the jpayne@68: translator’s codeset to the current locale’s jpayne@68: codeset, unless overridden by a prior call to the jpayne@68: bind_textdomain_codeset function.
jpayne@68: jpayne@68:The message jpayne@68: catalog used by the functions is at the pathname jpayne@68: dirname/locale/category/domainname.mo. jpayne@68: Here dirname is the directory specified through jpayne@68: bindtextdomain. Its default is system and jpayne@68: configuration dependent; typically it is jpayne@68: prefix/share/locale, where prefix is the jpayne@68: installation prefix of the package. locale is the jpayne@68: name of the current locale facet; the GNU implementation jpayne@68: also tries generalizations, such as the language name jpayne@68: without the territory name. category is jpayne@68: LC_MESSAGES for the gettext and jpayne@68: dgettext functions, or the argument passed to the jpayne@68: dcgettext function.
jpayne@68: jpayne@68:If the jpayne@68: LANGUAGE environment variable is set to a nonempty jpayne@68: value, and the locale is not the "C" locale, the jpayne@68: value of LANGUAGE is assumed to contain a colon jpayne@68: separated list of locale names. The functions will attempt jpayne@68: to look up a translation of msgid in each of the jpayne@68: locales in turn. This is a GNU extension.
jpayne@68: jpayne@68:In the jpayne@68: "C" locale, or if none of the used catalogs jpayne@68: contain a translation for msgid, the gettext, jpayne@68: dgettext and dcgettext functions return jpayne@68: msgid.
jpayne@68: jpayne@68:If a jpayne@68: translation was found in one of the specified catalogs, it jpayne@68: is converted to the locale’s codeset and returned. The jpayne@68: resulting string is statically allocated and must not be jpayne@68: modified or freed. Otherwise msgid is returned.
jpayne@68: jpayne@68:errno is jpayne@68: not modified.
jpayne@68: jpayne@68:The return type jpayne@68: ought to be const char *, but is char * to jpayne@68: avoid warnings in C code predating ANSI C.
jpayne@68: jpayne@68:When an empty jpayne@68: string is used for msgid, the functions may return a jpayne@68: nonempty string.
jpayne@68: jpayne@68:ngettext(3), jpayne@68: dngettext(3), dcngettext(3), jpayne@68: setlocale(3), textdomain(3), jpayne@68: bindtextdomain(3), bind_textdomain_codeset(3), jpayne@68: msgfmt(1)
jpayne@68: