I18N

I18N

Synopsis


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

#define             _                                   (String)
#define             Q_                                  (String)
#define             C_                                  (Context,String)
#define             N_                                  (String)
#define             NC_                                 (Context, String)
const gchar *       g_dgettext                          (const gchar *domain,
                                                         const gchar *msgid);
const gchar *       g_dcgettext                         (const gchar *domain,
                                                         const gchar *msgid,
                                                         int category);
const gchar *       g_dngettext                         (const gchar *domain,
                                                         const gchar *msgid,
                                                         const gchar *msgid_plural,
                                                         gulong n);
const gchar *       g_dpgettext                         (const gchar *domain,
                                                         const gchar *msgctxtid,
                                                         gsize msgidoffset);
const gchar *       g_dpgettext2                        (const gchar *domain,
                                                         const gchar *context,
                                                         const gchar *msgid);
const gchar *       g_strip_context                     (const gchar *msgid,
                                                         const gchar *msgval);

const gchar* const * g_get_language_names               (void);
gchar **            g_get_locale_variants               (const gchar *locale);

Description

Details

_()

#define             _(String)

String :


Q_()

#define             Q_(String)

String :


C_()

#define             C_(Context,String)

Context :

String :


N_()

#define             N_(String)

String :


NC_()

#define             NC_(Context, String)

Context :

String :


g_dgettext ()

const gchar *       g_dgettext                          (const gchar *domain,
                                                         const gchar *msgid);

This function is a wrapper of dgettext() which does not translate the message if the default domain as set with textdomain() has no translations for the current locale.

The advantage of using this function over dgettext() 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 textdomain() and setlocale() should precede any g_dgettext() invocations. For GTK+, it means calling textdomain() before gtk_init or its variants.

This function disables translations if and only if upon its first call all the following conditions hold:

  • domain is not NULL
  • textdomain() has been called to set a default text domain
  • there is no translations available for the default text domain and the current locale
  • current locale is not "C" or any English locales (those starting with "en_")

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 textdomain() after initializing GTK+.

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

domain :

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

msgid :

message to translate

Returns :

The translated string

Since 2.18


g_dcgettext ()

const gchar *       g_dcgettext                         (const gchar *domain,
                                                         const gchar *msgid,
                                                         int category);

This is a variant of g_dgettext() that allows specifying a locale category instead of always using LC_MESSAGES. See g_dgettext() for more information about how this functions differs from calling dcgettext() directly.

domain :

allow-none. allow-none.

msgid :

message to translate

category :

a locale category

Returns :

the translated string for the given locale category

Since 2.26


g_dngettext ()

const gchar *       g_dngettext                         (const gchar *domain,
                                                         const gchar *msgid,
                                                         const gchar *msgid_plural,
                                                         gulong n);

This function is a wrapper of dngettext() which does not translate the message if the default domain as set with textdomain() has no translations for the current locale.

See g_dgettext() for details of how this differs from dngettext() proper.

domain :

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

msgid :

message to translate

msgid_plural :

plural form of the message

n :

the quantity for which translation is needed

Returns :

The translated string

Since 2.18


g_dpgettext ()

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

This function is a variant of g_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.

This uses g_dgettext() internally. See that functions for differences with dgettext() proper.

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_dpgettext2 ()

const gchar *       g_dpgettext2                        (const gchar *domain,
                                                         const gchar *context,
                                                         const gchar *msgid);

This function is a variant of g_dgettext() which supports a disambiguating message context. GNU gettext uses the '\004' character to separate the message context and message id in msgctxtid.

This uses g_dgettext() internally. See that functions for differences with dgettext() proper.

This function differs from C_() in that it is not a macro and thus you may use non-string-literals as context and msgid arguments.

domain :

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

context :

the message context

msgid :

the message

Returns :

The translated string

Since 2.18


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_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 :

array zero-terminated=1) (transfer none. array zero-terminated=1. transfer none.

Since 2.6


g_get_locale_variants ()

gchar **            g_get_locale_variants               (const gchar *locale);

Returns a list of derived variants of locale, 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. This function handles territory, charset and extra locale modifiers.

For example, if locale is "fr_BE", then the returned list is "fr_BE", "fr".

If you need the list of variants for the current locale, use g_get_language_names().

locale :

a locale identifier

Returns :

transfer full) (array zero-terminated=1) (element-type utf8. transfer full. array zero-terminated=1. element-type utf8.

Since 2.28