Penguin
Recent Changes
Annotated edit history of gettext(3) version 4, including all changes. View license author blame.
Rev Author # Line
1 perry 1 GETTEXT
2 !!!GETTEXT
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 ERRORS
8 BUGS
9 SEE ALSO
10 ----
11 !!NAME
12
13
14 gettext, dgettext, dcgettext - translate message
15 !!SYNOPSIS
16
17
18 __#include
19 __ ''msgid''__);
20 char * dgettext (const char *__ ''domainname''__, const char *__ ''msgid''__);
21 char * dcgettext (const char *__ ''domainname''__, const char *__ ''msgid''__,
22 int__ ''category''__);
23 __
24 !!DESCRIPTION
25
26
27 The __gettext__, __dgettext__ and __dcgettext__
28 functions attempt to translate a text string into the user's
29 native language, by looking up the translation in a message
30 catalog.
31
32
33 The ''msgid'' argument identifies the message to be
34 translated. By convention, it is the English version of the
35 message, with non-ASCII characters replaced by ASCII
36 approximations. This choice allows the translators to work
37 with message catalogs, called PO files, that contain both
38 the English and the translated versions of each message, and
39 can be installed using the __msgfmt__
40 utility.
41
42
43 A message domain is a set of translatable ''msgid''
44 messages. Usually, every software package has its own
45 message domain. The domain name is used to determine the
46 message catalog where the translation is looked up; it must
47 be a non-empty string. For the __gettext__ function, it
48 is specified through a preceding __textdomain__ call. For
49 the __dgettext__ and __dcgettext__ functions, it is
50 passed as the ''domainname'' argument; if this argument
51 is NULL, the domain name specified through a preceding
52 __textdomain__ call is used instead.
53
54
55 Translation lookup operates in the context of the current
56 locale. For the __gettext__ and __dgettext__
57 functions, the __LC_MESSAGES__ locale facet is used. It
58 is determined by a preceding call to the __setlocale__
59 function. __setlocale(LC_ALL,__ initializes
60 the __LC_MESSAGES__ locale based on the first nonempty
61 value of the three environment variables __LC_ALL__,
62 __LC_MESSAGES__, __LANG__; see setlocale(3).
63 For the __dcgettext__ function, the locale facet is
64 determined by the ''category'' argument, which should be
65 one of the __LC_xxx__ constants defined in the
66 __LC_ALL__. In both
67 cases, the functions also use the __LC_CTYPE__ locale
68 facet in order to convert the translated message from the
69 translator's codeset to the current locale's codeset, unless
70 overridden by a prior call to the
71 __bind_textdomain_codeset__ function.
72
73
74 The message catalog used by the functions is at the pathname
75 ''dirname''/''locale''/''category''/''domainname''.mo.
76 Here ''dirname'' is the directory specified through
77 __bindtextdomain__. Its default is system and
78 configuration dependent; typically it is
79 ''prefix''/share/locale, where ''prefix'' is the
80 installation prefix of the package. ''locale'' is the
81 name of the current locale facet; the GNU implementation
82 also tries generalizations, such as the language name
83 without the territory name. ''category'' is
84 __LC_MESSAGES__ for the __gettext__ and
85 __dgettext__ functions, or the argument passed to the
86 __dcgettext__ function.
87
88
89 If the __LANGUAGE__ environment variable is set to a
90 nonempty value, and the locale is not the
91 __LANGUAGE__ is assumed to contain a
92 colon separated list of locale names. The functions will
93 attempt to look up a translation of ''msgid'' in each of
94 the locales in turn. This is a GNU extension.
95
96
97 In the
98 msgid'', the __gettext__,
99 __dgettext__ and __dcgettext__ functions return
100 ''msgid''.
101 !!RETURN VALUE
102
103
104 If a translation was found in one of the specified catalogs,
105 it is converted to the locale's codeset and returned. The
106 resulting string is statically allocated and must not be
107 modified or freed. Otherwise ''msgid'' is
108 returned.
109 !!ERRORS
110
111
112 __errno__ is not modified.
113 !!BUGS
114
115
116 The return type ought to be __const char *__, but is
117 __char *__ to avoid warnings in C code predating ANSI
118 C.
119
120
121 When an empty string is used for ''msgid'', the functions
122 may return a nonempty string.
123 !!SEE ALSO
124
125
126 ngettext(3), dngettext(3),
127 dcngettext(3), setlocale(3),
128 textdomain(3), bindtextdomain(3),
4 perry 129 bind_textdomain_codeset(3),
1 perry 130 msgfmt(1)
131 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.