i18n.sgml   [plain text]

<!-- ##### 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>
</para>

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

<!-- ##### MACRO _ ##### -->
<para>
Marks a string for translation, gets replaced with the translated string
at runtime.
</para>

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


<!-- ##### MACRO Q_ ##### -->
<para>
Like _(), but applies g_strip_context() to the translation. 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>

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


<!-- ##### 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: