Internationalization

Internationalization — gettext support macros

Synopsis


#include <glib.h>
#include <glib/gi18n.h>


#define             Q_                                  (String)
#define             C_                                  (Context,String)
#define             N_                                  (String)
const gchar*        g_strip_context                     (const gchar *msgid,
                                                         const gchar *msgval);
const gchar*        g_dpgettext                         (const gchar *domain,
                                                         const gchar *msgctxtid,
                                                         gsize msgidoffset);

const gchar* const * g_get_language_names               (void);

Description

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.

In order to use these macros in an application, you must include glib/gi18n.h. For use in a library, must include glib/gi18n-lib.h after defining the GETTEXT_PACKAGE macro suitably for your library: 

#define GETTEXT_PACKAGE "gtk20"
#include <glib/gi18n-lib.h>

The gettext manual covers details of how to set up message extraction with xgettext.

Details

Q_()

#define             Q_(String)

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.

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".

See the C_() macro for a different way to mark up translatable strings with context.

Note

If you are using the Q_() macro, you need to make sure that you pass --keyword=Q_ to xgettext when extracting messages. If you are using GNU gettext >= 0.15, you can also use --keyword=Q_:1g to let xgettext split the context string off into a msgctxt line in the po file.

String :

 the string to be translated, with a '|'-separated prefix which must not be translated

Returns :

 the translated message

Since 2.4

C_()

#define             C_(Context,String)

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. 

label1 = C_("Navigation", "Back");
label2 = C_("Body part", "Back");

Note

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

Context :

 a message context, must be a string literal

String :

 a message id, must be a string literal

Returns :

 the translated message

Since 2.16

N_()

#define             N_(String)

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 gettext() at runtime. 

     {
       static const char *messages[] = {
         N_("some very meaningful message"),
         N_("and another one")
       };
       const char *string;
       ...
       string
         = index > 1 ? _("a default message") : gettext (messages[index]);
     
       fputs (string);
       ...
     }

String :

 the string to be translated

Since 2.4

g_strip_context ()

const gchar*        g_strip_context                     (const gchar *msgid,
                                                         const gchar *msgval);

An auxiliary function for gettext() support (see Q_()).

msgid :

 a string

msgval :

 another string

Returns :

 msgval, unless msgval is identical to msgid and contains a '|' character, in which case a pointer to the substring of msgid after the first '|' character is returned.

Since 2.4

g_dpgettext ()

const gchar*        g_dpgettext                         (const gchar *domain,
                                                         const gchar *msgctxtid,
                                                         gsize msgidoffset);

This function is a variant of dgettext() which supports a disambiguating message context. GNU gettext uses the '\004' character to separate the message context and message id in msgctxtid. If 0 is passed as msgidoffset, this function will fall back to trying to use the deprecated convention of using "|" as a separation character.

Applications should normally not use this function directly, but use the C_() macro for translations with context.

domain :

 the translation domain to use, or NULL to use the domain set with textdomain()

msgctxtid :

 a combined message context and message id, separated by a \004 character

msgidoffset :

 the offset of the message id in msgctxid

Returns :

 The translated string

Since 2.16

g_get_language_names ()

const gchar* const * g_get_language_names               (void);

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".

For example, if LANGUAGE=de:en_US, then the returned list is "de", "en_US", "en", "C".

This function consults the environment variables LANGUAGE, LC_ALL, LC_MESSAGES and LANG to find the list of locales specified by the user.

Returns :

 a NULL-terminated array of strings owned by GLib that must not be modified or freed.

Since 2.6

See Also

The gettext manual.