i18n.xml   [plain text]

<refentry id="glib-I18N">
<refmeta>
<refentrytitle>Internationalization</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Internationalization</refname><refpurpose>gettext support macros.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;
#include &lt;glib/gi18n.h&gt;


#define     <link linkend="gettext-macro">_</link>                               (String)
#define     <link linkend="Q--CAPS">Q_</link>                              (String)
#define     <link linkend="N--CAPS">N_</link>                              (String)
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-strip-context">g_strip_context</link>       (const <link linkend="gchar">gchar</link> *msgid,
                                             const <link linkend="gchar">gchar</link> *msgval);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>
GLib doesn't force any particular localization method upon its users.
But since GLib itself is localized using the <link linkend="gettext"><function>gettext()</function></link> mechanism, it seems
natural to offer the de-facto standard <link linkend="gettext"><function>gettext()</function></link> 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>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="gettext-macro"/>_()</title>
<indexterm role="2.4"><primary>_</primary></indexterm><programlisting>#define     _(String)</programlisting>
<para>
Marks a string for translation, gets replaced with the translated string
at runtime.
</para><variablelist role="params">
<varlistentry><term><parameter>String</parameter>&nbsp;:</term>
<listitem><simpara>the string to be translated
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4


</para></refsect2>
<refsect2>
<title><anchor id="Q--CAPS"/>Q_()</title>
<indexterm role="2.4"><primary>Q_</primary></indexterm><programlisting>#define     Q_(String)</programlisting>
<para>
Like <link linkend="gettext-macro"><function>_()</function></link>, but applies <link linkend="g-strip-context"><function>g_strip_context()</function></link> 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><variablelist role="params">
<varlistentry><term><parameter>String</parameter>&nbsp;:</term>
<listitem><simpara>the string to be translated, with a '|'-separated prefix which 
  must not be translated
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4


</para></refsect2>
<refsect2>
<title><anchor id="N--CAPS"/>N_()</title>
<indexterm role="2.4"><primary>N_</primary></indexterm><programlisting>#define     N_(String)</programlisting>
<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><variablelist role="params">
<varlistentry><term><parameter>String</parameter>&nbsp;:</term>
<listitem><simpara>the string to be translated
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4


</para></refsect2>
<refsect2>
<title><anchor id="g-strip-context"/>g_strip_context ()</title>
<indexterm role="2.4"><primary>g_strip_context</primary></indexterm><programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_strip_context       (const <link linkend="gchar">gchar</link> *msgid,
                                             const <link linkend="gchar">gchar</link> *msgval);</programlisting>
<para>
An auxiliary function for <link linkend="gettext"><function>gettext()</function></link> support (see <link linkend="Q--CAPS"><function>Q_()</function></link>).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>msgid</parameter>&nbsp;:</term>
<listitem><simpara> a string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>msgval</parameter>&nbsp;:</term>
<listitem><simpara> another string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>msgval</parameter>, unless <parameter>msgval</parameter> is identical to <parameter>msgid</parameter> and contains
  a '|' character, in which case a pointer to the substring of msgid after
  the first '|' character is returned. 

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.4
</para></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
The gettext manual.
</para>
</refsect1>

</refentry>