1GETTEXT(3) Library Functions Manual GETTEXT(3)
2
6 gettext, dgettext, dcgettext - translate message
7
9 #include <libintl.h>
10 char * gettext (const char * msgid);
12 char * dgettext (const char * domainname, const char * msgid);
13 char * dcgettext (const char * domainname, const char * msgid,
14 int category);
15
17 The gettext, dgettext and dcgettext functions attempt to translate a
18 text string into the user's native language, by looking up the transla‐
19 tion in a message catalog.
20 The msgid argument identifies the message to be translated. By conven‐
22 tion, it is the English version of the message, with non-ASCII charac‐
23 ters replaced by ASCII approximations. This choice allows the transla‐
24 tors to work with message catalogs, called PO files, that contain both
25 the English and the translated versions of each message, and can be in‐
26 stalled using the msgfmt utility.
27 A message domain is a set of translatable msgid messages. Usually, ev‐
29 ery software package has its own message domain. The domain name is
30 used to determine the message catalog where the translation is looked
31 up; it must be a non-empty string. For the gettext function, it is
32 specified through a preceding textdomain call. For the dgettext and
33 dcgettext functions, it is passed as the domainname argument; if this
34 argument is NULL, the domain name specified through a preceding textdo‐
35 main call is used instead.
36 Translation lookup operates in the context of the current locale. For
38 the gettext and dgettext functions, the LC_MESSAGES locale facet is
39 used. It is determined by a preceding call to the setlocale function.
40 setlocale(LC_ALL,"") initializes the LC_MESSAGES locale based on the
41 first nonempty value of the three environment variables LC_ALL, LC_MES‐
42 SAGES, LANG; see setlocale(3). For the dcgettext function, the locale
43 facet is determined by the category argument, which should be one of
44 the LC_xxx constants defined in the <locale.h> header, excluding
45 LC_ALL. In both cases, the functions also use the LC_CTYPE locale facet
46 in order to convert the translated message from the translator's code‐
47 set to the current locale's codeset, unless overridden by a prior call
48 to the bind_textdomain_codeset function.
49 The message catalog used by the functions is at the pathname
51 dirname/locale/category/domainname.mo. Here dirname is the directory
52 specified through bindtextdomain. Its default is system and configura‐
53 tion dependent; typically it is prefix/share/locale, where prefix is
54 the installation prefix of the package. locale is the name of the cur‐
55 rent locale facet; the GNU implementation also tries generalizations,
56 such as the language name without the territory name. category is
57 LC_MESSAGES for the gettext and dgettext functions, or the argument
58 passed to the dcgettext function.
59 If the LANGUAGE environment variable is set to a nonempty value, and
61 the locale is not the "C" locale, the value of LANGUAGE is assumed to
62 contain a colon separated list of locale names. The functions will at‐
63 tempt to look up a translation of msgid in each of the locales in turn.
64 This is a GNU extension.
65 In the "C" locale, or if none of the used catalogs contain a transla‐
67 tion for msgid, the gettext, dgettext and dcgettext functions return
68 msgid.
69
71 If a translation was found in one of the specified catalogs, it is con‐
72 verted to the locale's codeset and returned. The resulting string is
73 statically allocated and must not be modified or freed. Otherwise msgid
74 is returned.
75
77 errno is not modified.
78
80 The return type ought to be const char *, but is char * to avoid warn‐
81 ings in C code predating ANSI C.
82 When an empty string is used for msgid, the functions may return a
84 nonempty string.
85
87 ngettext(3), dngettext(3), dcngettext(3), setlocale(3), textdomain(3),
88 bindtextdomain(3), bind_textdomain_codeset(3), msgfmt(1)
89GNU gettext 20220912 May 2001 GETTEXT(3)