1 <!-- ##### SECTION Title ##### --> 2 Internationalization 3 4 <!-- ##### SECTION Short_Description ##### --> 5 gettext support macros 6 7 <!-- ##### SECTION Long_Description ##### --> 8 <para> 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 12 easy-to-use form. 13 </para> 14 <para> 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 24 with xgettext. 25 </para> 26 27 <!-- ##### SECTION See_Also ##### --> 28 <para> 29 The gettext manual. 30 </para> 31 32 <!-- ##### SECTION Stability_Level ##### --> 33 34 35 <!-- ##### MACRO Q_ ##### --> 36 <para> 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. 40 </para> 41 <para> 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 47 "language|Russian". 48 </para> 49 <para> 50 See the C_() macro for a different way to mark up translatable strings 51 with context. 52 </para> 53 <note><para> 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. 59 </para></note> 60 61 @String: the string to be translated, with a '|'-separated prefix which 62 must not be translated 63 @Returns: the translated message 64 @Since: 2.4 65 66 67 <!-- ##### MACRO C_ ##### --> 68 <para> 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 72 they are used. 73 <informalexample><programlisting> 74 label1 = C_("Navigation", "Back"); 75 label2 = C_("Body part", "Back"); 76 </programlisting></informalexample> 77 </para> 78 79 <note><para> 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. 83 </para></note> 84 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 88 @Since: 2.16 89 90 91 <!-- ##### MACRO N_ ##### --> 92 <para> 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. 97 </para> 98 <informalexample><programlisting> 99 { 100 static const char *messages[] = { 101 N_("some very meaningful message"), 102 N_("and another one") 103 }; 104 const char *string; 105 ... 106 string 107 = index > 1 ? _("a default message") : gettext (messages[index]); 108 <!-- --> 109 fputs (string); 110 ... 111 } 112 </programlisting></informalexample> 113 114 @String: the string to be translated 115 @Since: 2.4 116 117 118 <!-- ##### MACRO NC_ ##### --> 119 <para> 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. 124 </para> 125 |[ 126 { 127 static const char *messages[] = { 128 NC_("some context", "some very meaningful message"), 129 NC_("some context", "and another one") 130 }; 131 const char *string; 132 ... 133 string 134 = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message") : g_dpgettext2 (NULL, "some context", messages[index]); 135 <!-- --> 136 fputs (string); 137 ... 138 } 139 ]| 140 141 <note><para> 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. 146 </para></note> 147 148 @Context: a message context, must be a string literal 149 @String: a message id, must be a string literal 150 @Since: 2.18 151 152 153 <!-- ##### FUNCTION g_dgettext ##### --> 154 <para> 155 156 </para> 157 158 @domain: 159 @msgid: 160 @Returns: 161 162 163 <!-- ##### FUNCTION g_dngettext ##### --> 164 <para> 165 166 </para> 167 168 @domain: 169 @msgid: 170 @msgid_plural: 171 @n: 172 @Returns: 173 174 175 <!-- ##### FUNCTION g_dpgettext ##### --> 176 <para> 177 178 </para> 179 180 @domain: 181 @msgctxtid: 182 @msgidoffset: 183 @Returns: 184 185 186 <!-- ##### FUNCTION g_dpgettext2 ##### --> 187 <para> 188 189 </para> 190 191 @domain: 192 @context: 193 @msgid: 194 @Returns: 195 196 197 <!-- ##### FUNCTION g_strip_context ##### --> 198 <para> 199 200 </para> 201 202 @msgid: 203 @msgval: 204 @Returns: 205 206 207 <!-- ##### FUNCTION g_get_language_names ##### --> 208 <para> 209 210 </para> 211 212 @Returns: 213 214 215
