version 4 showing authors affecting page license.
.
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), |
|
|
129 |
bind_textdomain_codeset(3), |
|
|
130 |
msgfmt(1) |
|
|
131 |
---- |