docs/reference/glib/tmpl/i18n.sgml

<!-- ##### SECTION Title ##### -->
Internationalization

<!-- ##### SECTION Short_Description ##### -->
gettext support macros

<!-- ##### SECTION Long_Description ##### -->
<para>
GLib doesn't force any particular localization method upon its users.
But since GLib itself is localized using the gettext() mechanism, it seems
natural to offer the de-facto standard gettext() support macros in an 
easy-to-use form.
</para>
<para>
In order to use these macros in an application, you must include 
<filename>glib/gi18n.h</filename>. For use in a library, must include
<filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining
the GETTEXT_PACKAGE macro suitably for your library:
<informalexample><programlisting>
&num;define GETTEXT_PACKAGE "gtk20"
&num;include &lt;glib/gi18n-lib.h&gt;
</programlisting></informalexample>
The gettext manual covers details of how to set up message extraction
with xgettext.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
The gettext manual.
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### MACRO Q_ ##### -->
<para>
Like _(), but handles context in message ids. This has the advantage that 
the string can be adorned with a prefix to guarantee uniqueness and provide 
context to the translator. 
</para>
<para>
One use case given in the gettext manual is GUI translation, where one could 
e.g. disambiguate two "Open" menu entries as "File|Open" and "Printer|Open". 
Another use case is the string "Russian" which may have to be translated
differently depending on whether it's the name of a character set or a 
language. This could be solved by using "charset|Russian" and 
"language|Russian".
</para>
<para>
See the C_() macro for a different way to mark up translatable strings
with context.
</para>
<note><para>
If you are using the Q_() macro, you need to make sure that you 
pass <option>--keyword=Q_</option> to xgettext when extracting messages.
If you are using GNU gettext >= 0.15, you can also use
<option>--keyword=Q_:1g</option> to let xgettext split the context
string off into a msgctxt line in the po file.
</para></note>

@String: the string to be translated, with a '|'-separated prefix which 
  must not be translated
@Returns: the translated message
@Since: 2.4


<!-- ##### MACRO C_ ##### -->
<para>
Uses gettext to get the translation for @msgid. @msgctxt is 
used as a context. This is mainly useful for short strings which 
may need different translations, depending on the context in which 
they are used.
<informalexample><programlisting>
label1 = C_("Navigation", "Back");
label2 = C_("Body part", "Back");
</programlisting></informalexample> 
</para>

<note><para>
If you are using the C_() macro, you need to make sure that you 
pass <option>--keyword=C_:1c,2</option> to xgettext when extracting 
messages. Note that this only works with GNU gettext >= 0.15. 
</para></note>

@Context: 
@String: 
@Returns: the translated message
@Since: 2.16
<!-- # Unused Parameters # -->
@msgctxt: a message context, must be a string literal
@msgid: a message id, must be a string literal


<!-- ##### MACRO N_ ##### -->
<para>
Marks a string for translation, gets replaced with the untranslated string
at runtime. This is useful in situations where the translated strings can't
be directly used, e.g. in string array initializers. 
</para>
<informalexample><programlisting>
     {
       static const char *messages[] = {
         N_("some very meaningful message"),
         N_("and another one")
       };
       const char *string;
       ...
       string
         = index &gt; 1 ? _("a default message") : gettext (messages[index]);
<!-- -->     
       fputs (string);
       ...
     }
</programlisting></informalexample>

@String: the string to be translated
@Since: 2.4


<!-- ##### FUNCTION g_strip_context ##### -->
<para>

</para>

@msgid: 
@msgval: 
@Returns: 


<!-- ##### FUNCTION g_dpgettext ##### -->
<para>

</para>

@domain: 
@msgctxtid: 
@msgidoffset: 
@Returns: 


<!-- ##### FUNCTION g_get_language_names ##### -->
<para>

</para>

@Returns: