## Internationalization

Internationalization — gettext support macros

## Functions

#define | _()
#define | Q_()
#define | C_()
#define | N_()
#define | NC_()
const gchar * | g_dgettext ()
const gchar * | g_dcgettext ()
const gchar * | g_dngettext ()
const gchar * | g_dpgettext ()
const gchar * | g_dpgettext2 ()
const gchar * | g_strip_context ()
const gchar * const * | g_get_language_names ()
gchar ** | g_get_locale_variants ()

## Includes

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

## 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, you must include `<glib/gi18n-lib.h>` after defining the `GETTEXT_PACKAGE` macro suitably for your library:

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

For an application, note that you also have to call `bindtextdomain()`, `bind_textdomain_codeset()`, `textdomain()` and `setlocale()` early on in your `main()` to make `gettext()` work. For example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    #include <glib/gi18n.h>
    #include <locale.h>

    int
    main (int argc, char **argv)
    {
      setlocale (LC_ALL, "");
      bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale");
      bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
      textdomain (GETTEXT_PACKAGE);

      // Rest of your application.
    }

where `DATADIR` is as typically provided by automake.

For a library, you only have to call `bindtextdomain()` and `bind_textdomain_codeset()` in your initialization function. If your library doesn't have an initialization function, you can call the functions before the first translated message.

The gettext manual covers details of how to integrate gettext into a project’s build system and workflow.

## Functions

### _()

    #define             _(String)

Marks a string for translation, gets replaced with the translated string at runtime.

#### Parameters

String | the string to be translated |

Since: 2.4

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

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.

#### Parameters

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 `String` . `Context` 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.

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

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.

#### Parameters

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.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {
      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);
      ...
    }

#### Parameters

String | the string to be translated |

Since: 2.4

### NC_()

    #define             NC_(Context, String)

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    {
      static const char *messages[] = {
        NC_("some context", "some very meaningful message"),
        NC_("some context", "and another one")
      };
      const char *string;
      ...
      string
        = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message")
                    : g_dpgettext2 (NULL, "some context", messages[index]);

      fputs (string);
      ...
    }

If you are using the `NC_()` macro, you need to make sure that you pass `--keyword=NC_:1c,2` to xgettext when extracting messages. Note that this only works with GNU gettext >= 0.15. Intltool has support for the `NC_()` macro since version 0.40.1.

#### Parameters

Context | a message context, must be a string literal |
String | a message id, must be a string literal |

Since: 2.18

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

#### Parameters

domain | the translation domain to use, or `NULL` to use the domain set with `textdomain()`. | [allow-none]
msgid | message to translate |

#### Returns

The translated string

Since: 2.18

### g_dcgettext ()

    const gchar *
    g_dcgettext (const gchar *domain,
                 const gchar *msgid,
                 gint 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.

#### Parameters

domain | the translation domain to use, or `NULL` to use the domain set with `textdomain()`. | [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.

#### Parameters

domain | the translation domain to use, or `NULL` to use the domain set with `textdomain()`. | [allow-none]
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.

#### Parameters

domain | the translation domain to use, or `NULL` to use the domain set with `textdomain()`. | [allow-none]
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.

#### Parameters

domain | the translation domain to use, or `NULL` to use the domain set with `textdomain()`. | [allow-none]
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_()`).

#### Parameters

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

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

[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()`.

#### Parameters

locale | a locale identifier |

#### Returns

a newly allocated array of newly allocated strings with the locale variants. Free with `g_strfreev()`.

[transfer full][array zero-terminated=1][element-type utf8]

Since: 2.28

## Types and Values

## See Also

the gettext manual