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

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

<refsynopsisdiv id="glib-I18N.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

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

#define             <link linkend="Q---CAPS">Q_</link>                                  (String)
#define             <link linkend="C---CAPS">C_</link>                                  (Context,String)
#define             <link linkend="N---CAPS">N_</link>                                  (String)
#define             <link linkend="NC---CAPS">NC_</link>                                 (Context, String)
const <link linkend="gchar">gchar</link> *       <link linkend="g-dgettext">g_dgettext</link>                          (const <link linkend="gchar">gchar</link> *domain,
                                                         const <link linkend="gchar">gchar</link> *msgid);
const <link linkend="gchar">gchar</link> *       <link linkend="g-dngettext">g_dngettext</link>                         (const <link linkend="gchar">gchar</link> *domain,
                                                         const <link linkend="gchar">gchar</link> *msgid,
                                                         const <link linkend="gchar">gchar</link> *msgid_plural,
                                                         <link linkend="gulong">gulong</link> n);
const <link linkend="gchar">gchar</link> *       <link linkend="g-dpgettext">g_dpgettext</link>                         (const <link linkend="gchar">gchar</link> *domain,
                                                         const <link linkend="gchar">gchar</link> *msgctxtid,
                                                         <link linkend="gsize">gsize</link> msgidoffset);
const <link linkend="gchar">gchar</link> *       <link linkend="g-dpgettext2">g_dpgettext2</link>                        (const <link linkend="gchar">gchar</link> *domain,
                                                         const <link linkend="gchar">gchar</link> *context,
                                                         const <link linkend="gchar">gchar</link> *msgid);
const <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);

const <link linkend="gchar">gchar</link>* const * <link linkend="g-get-language-names">g_get_language_names</link>               (void);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-I18N.description" role="desc">
<title role="desc.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>
The gettext manual covers details of how to set up message extraction
with xgettext.
</para>
</refsect1>

<refsect1 id="glib-I18N.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="Q---CAPS" role="macro" condition="since:2.4">
<title>Q_()</title>
<indexterm zone="Q---CAPS" role="2.4"><primary>Q_</primary></indexterm><programlisting>#define             Q_(String)</programlisting>
<para>
Like <link linkend="gettext-macro"><function>_()</function></link>, 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 <link linkend="C---CAPS"><function>C_()</function></link> macro for a different way to mark up translatable strings
with context.
</para>
<note><para>
If you are using the <link linkend="Q---CAPS"><function>Q_()</function></link> 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><variablelist role="params">
<varlistentry><term><parameter>String</parameter>&#160;:</term>
<listitem><simpara>the string to be translated, with a '|'-separated prefix which 
  must not be translated
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the translated message
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="C---CAPS" role="macro" condition="since:2.16">
<title>C_()</title>
<indexterm zone="C---CAPS" role="2.16"><primary>C_</primary></indexterm><programlisting>#define             C_(Context,String)</programlisting>
<para>
Uses gettext to get the translation for <parameter>msgid</parameter>. <parameter>msgctxt</parameter> 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 <link linkend="C---CAPS"><function>C_()</function></link> 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><variablelist role="params">
<varlistentry><term><parameter>Context</parameter>&#160;:</term>
<listitem><simpara>a message context, must be a string literal
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>String</parameter>&#160;:</term>
<listitem><simpara>a message id, must be a string literal
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the translated message
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="N---CAPS" role="macro" condition="since:2.4">
<title>N_()</title>
<indexterm zone="N---CAPS" role="2.4"><primary>N_</primary></indexterm><programlisting>#define             N_(String)</programlisting>
<para>
Only marks a string for translation.
This is useful in situations where the translated strings can't
be directly used, e.g. in string array initializers.
To get the translated string, call <link linkend="gettext"><function>gettext()</function></link> at runtime.
</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>&#160;:</term>
<listitem><simpara>the string to be translated
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="NC---CAPS" role="macro" condition="since:2.18">
<title>NC_()</title>
<indexterm zone="NC---CAPS" role="2.18"><primary>NC_</primary></indexterm><programlisting>#define             NC_(Context, String)</programlisting>
<para>
Only marks a string for translation, with context.
This is useful in situations where the translated strings can't
be directly used, e.g. in string array initializers.
To get the translated string, you should call <link linkend="g-dpgettext2"><function>g_dpgettext2()</function></link> at runtime.
</para>
<informalexample><programlisting>
     {
       static const char *messages[] = {
         NC_("some context", "some very meaningful message"),
         NC_("some context", "and another one")
       };
       const char *string;
       ...
       string
         = index &gt; 1 ? g_dpgettext2 (NULL, "some context", "a default message") : g_dpgettext2 (NULL, "some context", messages[index]);
<!-- -->
       fputs (string);
       ...
     }
</programlisting></informalexample>
<note><para>
If you are using the <link linkend="NC---CAPS"><function>NC_()</function></link> macro, you need to make sure that you
pass <option>--keyword=NC_:1c,2</option> to xgettext when extracting
messages. Note that this only works with GNU gettext >= 0.15.
Intltool has support for the <link linkend="NC---CAPS"><function>NC_()</function></link> macro since version 0.40.1.
</para></note><variablelist role="params">
<varlistentry><term><parameter>Context</parameter>&#160;:</term>
<listitem><simpara>a message context, must be a string literal
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>String</parameter>&#160;:</term>
<listitem><simpara>a message id, must be a string literal
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.18</para></refsect2>
<refsect2 id="g-dgettext" role="function" condition="since:2.18">
<title>g_dgettext ()</title>
<indexterm zone="g-dgettext" role="2.18"><primary sortas="dgettext">g_dgettext</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       g_dgettext                          (const <link linkend="gchar">gchar</link> *domain,
                                                         const <link linkend="gchar">gchar</link> *msgid);</programlisting>
<para>
This function is a wrapper of <link linkend="dgettext"><function>dgettext()</function></link> which does not translate
the message if the default domain as set with <link linkend="textdomain"><function>textdomain()</function></link> has no
translations for the current locale.
</para>
<para>
The advantage of using this function over <link linkend="dgettext"><function>dgettext()</function></link> proper is that
libraries using this function (like GTK+) will not use translations
if the application using the library does not have translations for
the current locale.  This results in a consistent English-only
interface instead of one having partial translations.  For this
feature to work, the call to <link linkend="textdomain"><function>textdomain()</function></link> and <link linkend="setlocale"><function>setlocale()</function></link> should
precede any <link linkend="g-dgettext"><function>g_dgettext()</function></link> invocations.  For GTK+, it means calling
<link linkend="textdomain"><function>textdomain()</function></link> before gtk_init or its variants.
</para>
<para>
This function disables translations if and only if upon its first
call all the following conditions hold:
<itemizedlist>
<listitem><parameter>domain</parameter> is not <link linkend="NULL--CAPS"><literal>NULL</literal></link></listitem>
<listitem><link linkend="textdomain"><function>textdomain()</function></link> has been called to set a default text domain</listitem>
<listitem>there is no translations available for the default text domain
          and the current locale</listitem>
<listitem>current locale is not "C" or any English locales (those
          starting with "en_")</listitem>
</itemizedlist>
</para>
<para>
Note that this behavior may not be desired for example if an application
has its untranslated messages in a language other than English.  In those
cases the application should call <link linkend="textdomain"><function>textdomain()</function></link> after initializing GTK+.
</para>
<para>
Applications should normally not use this function directly,
but use the <link linkend="gettext-macro"><function>_()</function></link> macro for translations.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
<listitem><simpara> the translation domain to use, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to use
  the domain set with <link linkend="textdomain"><function>textdomain()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>msgid</parameter>&#160;:</term>
<listitem><simpara> message to translate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The translated string

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.18</para></refsect2>
<refsect2 id="g-dngettext" role="function" condition="since:2.18">
<title>g_dngettext ()</title>
<indexterm zone="g-dngettext" role="2.18"><primary sortas="dngettext">g_dngettext</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       g_dngettext                         (const <link linkend="gchar">gchar</link> *domain,
                                                         const <link linkend="gchar">gchar</link> *msgid,
                                                         const <link linkend="gchar">gchar</link> *msgid_plural,
                                                         <link linkend="gulong">gulong</link> n);</programlisting>
<para>
This function is a wrapper of <link linkend="dngettext"><function>dngettext()</function></link> which does not translate
the message if the default domain as set with <link linkend="textdomain"><function>textdomain()</function></link> has no
translations for the current locale.
</para>
<para>
See <link linkend="g-dgettext"><function>g_dgettext()</function></link> for details of how this differs from <link linkend="dngettext"><function>dngettext()</function></link>
proper.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
<listitem><simpara> the translation domain to use, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to use
  the domain set with <link linkend="textdomain"><function>textdomain()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>msgid</parameter>&#160;:</term>
<listitem><simpara> message to translate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>msgid_plural</parameter>&#160;:</term>
<listitem><simpara> plural form of the message
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara> the quantity for which translation is needed
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The translated string

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.18</para></refsect2>
<refsect2 id="g-dpgettext" role="function" condition="since:2.16">
<title>g_dpgettext ()</title>
<indexterm zone="g-dpgettext" role="2.16"><primary sortas="dpgettext">g_dpgettext</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       g_dpgettext                         (const <link linkend="gchar">gchar</link> *domain,
                                                         const <link linkend="gchar">gchar</link> *msgctxtid,
                                                         <link linkend="gsize">gsize</link> msgidoffset);</programlisting>
<para>
This function is a variant of <link linkend="g-dgettext"><function>g_dgettext()</function></link> which supports
a disambiguating message context. GNU gettext uses the
'\004' character to separate the message context and
message id in <parameter>msgctxtid</parameter>.
If 0 is passed as <parameter>msgidoffset</parameter>, this function will fall back to
trying to use the deprecated convention of using "|" as a separation
character.
</para>
<para>
This uses <link linkend="g-dgettext"><function>g_dgettext()</function></link> internally.  See that functions for differences
with <link linkend="dgettext"><function>dgettext()</function></link> proper.
</para>
<para>
Applications should normally not use this function directly,
but use the <link linkend="C---CAPS"><function>C_()</function></link> macro for translations with context.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
<listitem><simpara> the translation domain to use, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to use
  the domain set with <link linkend="textdomain"><function>textdomain()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>msgctxtid</parameter>&#160;:</term>
<listitem><simpara> a combined message context and message id, separated
  by a \004 character
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>msgidoffset</parameter>&#160;:</term>
<listitem><simpara> the offset of the message id in <parameter>msgctxid</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The translated string

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-dpgettext2" role="function" condition="since:2.18">
<title>g_dpgettext2 ()</title>
<indexterm zone="g-dpgettext2" role="2.18"><primary sortas="dpgettext2">g_dpgettext2</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       g_dpgettext2                        (const <link linkend="gchar">gchar</link> *domain,
                                                         const <link linkend="gchar">gchar</link> *context,
                                                         const <link linkend="gchar">gchar</link> *msgid);</programlisting>
<para>
This function is a variant of <link linkend="g-dgettext"><function>g_dgettext()</function></link> which supports
a disambiguating message context. GNU gettext uses the
'\004' character to separate the message context and
message id in <parameter>msgctxtid</parameter>.
</para>
<para>
This uses <link linkend="g-dgettext"><function>g_dgettext()</function></link> internally.  See that functions for differences
with <link linkend="dgettext"><function>dgettext()</function></link> proper.
</para>
<para>
This function differs from <link linkend="C---CAPS"><function>C_()</function></link> in that it is not a macro and 
thus you may use non-string-literals as context and msgid arguments.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
<listitem><simpara> the translation domain to use, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to use
  the domain set with <link linkend="textdomain"><function>textdomain()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>context</parameter>&#160;:</term>
<listitem><simpara> the message context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>msgid</parameter>&#160;:</term>
<listitem><simpara> the message
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The translated string

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.18</para></refsect2>
<refsect2 id="g-strip-context" role="function" condition="since:2.4">
<title>g_strip_context ()</title>
<indexterm zone="g-strip-context" role="2.4"><primary sortas="strip_context">g_strip_context</primary></indexterm><programlisting>const <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>&#160;:</term>
<listitem><simpara> a string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>msgval</parameter>&#160;:</term>
<listitem><simpara> another string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 role="since">Since 2.4</para></refsect2>
<refsect2 id="g-get-language-names" role="function" condition="since:2.6">
<title>g_get_language_names ()</title>
<indexterm zone="g-get-language-names" role="2.6"><primary sortas="get_language_names">g_get_language_names</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* const * g_get_language_names               (void);</programlisting>
<para>
Computes a list of applicable locale names, which can be used to 
e.g. construct locale-dependent filenames or search paths. The returned 
list is sorted from most desirable to least desirable and always contains 
the default locale "C".
</para>
<para>
For example, if LANGUAGE=de:en_US, then the returned list is
"de", "en_US", "en", "C".
</para>
<para>
This function consults the environment variables <envar>LANGUAGE</envar>, 
<envar>LC_ALL</envar>, <envar>LC_MESSAGES</envar> and <envar>LANG</envar> 
to find the list of locales specified by the user.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings owned by GLib 
   that must not be modified or freed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>

</refsect1>



<refsect1 id="glib-I18N.see-also">
<title>See Also</title>
<para>
The gettext manual.
</para>
</refsect1>

</refentry>
