1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
7 <!-- ##### SECTION Long_Description ##### -->
9 GLib doesn't force any particular localization method upon its users.
10 But since GLib itself is localized using the gettext() mechanism, it seems
11 natural to offer the de-facto standard gettext() support macros in an
15 In order to use these macros in an application, you must include
16 <filename>glib/gi18n.h</filename>. For use in a library, must include
17 <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining
18 the GETTEXT_PACKAGE macro suitably for your library:
19 <informalexample><programlisting>
20 #define GETTEXT_PACKAGE "gtk20"
21 #include <glib/gi18n-lib.h>
22 </programlisting></informalexample>
23 The gettext manual covers details of how to set up message extraction
27 <!-- ##### SECTION See_Also ##### -->
32 <!-- ##### SECTION Stability_Level ##### -->
35 <!-- ##### MACRO Q_ ##### -->
37 Like _(), but handles context in message ids. This has the advantage that
38 the string can be adorned with a prefix to guarantee uniqueness and provide
39 context to the translator.
42 One use case given in the gettext manual is GUI translation, where one could
43 e.g. disambiguate two "Open" menu entries as "File|Open" and "Printer|Open".
44 Another use case is the string "Russian" which may have to be translated
45 differently depending on whether it's the name of a character set or a
46 language. This could be solved by using "charset|Russian" and
50 See the C_() macro for a different way to mark up translatable strings
54 If you are using the Q_() macro, you need to make sure that you
55 pass <option>--keyword=Q_</option> to xgettext when extracting messages.
56 If you are using GNU gettext >= 0.15, you can also use
57 <option>--keyword=Q_:1g</option> to let xgettext split the context
58 string off into a msgctxt line in the po file.
61 @String: the string to be translated, with a '|'-separated prefix which
62 must not be translated
63 @Returns: the translated message
67 <!-- ##### MACRO C_ ##### -->
69 Uses gettext to get the translation for @msgid. @msgctxt is
70 used as a context. This is mainly useful for short strings which
71 may need different translations, depending on the context in which
73 <informalexample><programlisting>
74 label1 = C_("Navigation", "Back");
75 label2 = C_("Body part", "Back");
76 </programlisting></informalexample>
80 If you are using the C_() macro, you need to make sure that you
81 pass <option>--keyword=C_:1c,2</option> to xgettext when extracting
82 messages. Note that this only works with GNU gettext >= 0.15.
85 @Context: a message context, must be a string literal
86 @String: a message id, must be a string literal
87 @Returns: the translated message
91 <!-- ##### MACRO N_ ##### -->
93 Only marks a string for translation.
94 This is useful in situations where the translated strings can't
95 be directly used, e.g. in string array initializers.
96 To get the translated string, call gettext() at runtime.
98 <informalexample><programlisting>
100 static const char *messages[] = {
101 N_("some very meaningful message"),
102 N_("and another one")
107 = index > 1 ? _("a default message") : gettext (messages[index]);
112 </programlisting></informalexample>
114 @String: the string to be translated
118 <!-- ##### MACRO NC_ ##### -->
120 Only marks a string for translation, with context.
121 This is useful in situations where the translated strings can't
122 be directly used, e.g. in string array initializers.
123 To get the translated string, you should call g_dpgettext2() at runtime.
127 static const char *messages[] = {
128 NC_("some context", "some very meaningful message"),
129 NC_("some context", "and another one")
134 = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message") : g_dpgettext2 (NULL, "some context", messages[index]);
142 If you are using the NC_() macro, you need to make sure that you
143 pass <option>--keyword=NC_:1c,2</option> to xgettext when extracting
144 messages. Note that this only works with GNU gettext >= 0.15.
145 Intltool has support for the NC_() macro since version 0.40.1.
148 @Context: a message context, must be a string literal
149 @String: a message id, must be a string literal
153 <!-- ##### FUNCTION g_dgettext ##### -->
163 <!-- ##### FUNCTION g_dngettext ##### -->
175 <!-- ##### FUNCTION g_dpgettext ##### -->
186 <!-- ##### FUNCTION g_dpgettext2 ##### -->
197 <!-- ##### FUNCTION g_strip_context ##### -->
207 <!-- ##### FUNCTION g_get_language_names ##### -->