docs/reference/glib/tmpl/i18n.sgml

   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 &num;define GETTEXT_PACKAGE "gtk20"
  21 &num;include &lt;glib/gi18n-lib.h&gt;
  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 &gt; 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 &gt; 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