GLib – 2.0: Internationalization
Description: Reference for GLib-2.0: Internationalization

#### Internationalization

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:

    #define GETTEXT_PACKAGE "gtk4"
    #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:

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

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.

## Macros

GLib provides various convenience C pre-processor macros that make it easy for tools like `xgettext` to extract translatable strings from the source of a library or an application. These macros are defined when including `<glib/gi18n.h>` or `<glib/gi18n-lib.h>`.

`_(String)`
  Marks a string for translation. The string will be replaced by its translation at run time, if any exists; otherwise, it will be passed as is.
`N_(String)`

  Marks a string for translation. Unlike `_()`, this macro will not replace the string with its translation; this is useful when the translatable string is inside a `struct` or array declaration, for instance:

      static const char *messages[] = {
        N_("some very meaningful message"),
        N_("and another one"),
      };

  It is the responsibility of the developer to call `gettext()` when using the string, e.g.:

      g_print ("%s", idx >= G_N_ELEMENTS (messages)
               ? _("default message")
               : gettext (messages[idx]));

`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. For instance:

      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. This only works with a version of GNU gettext newer than 0.15.

  This macro is available since GLib 2.16

`NC_(Context, String)`

  Only marks a string for translation, with context. Similar to `N_()`, but allows you to add a context to the translatable string, for instance:

      static const char *messages[] = {
        NC_("some context", "some very meaningful message"),
        NC_("some context", "and another one")
      };

  It is the responsibility of the developer to call `g_dpgettext2()` when using the string, e.g.:

      g_print ("%s", idx >= G_N_ELEMENTS (messages)
               ? g_dpgettext2 (NULL, "some context", "a default message")
               : g_dpgettext2 (NULL, "some context", messages[idx]);

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

  This macro is available since GLib 2.18

`Q_(String)`

  Like `_()`, but handles context inside the translatable string. This has the advantage that the string can be adorned with a prefix to guarantee uniqueness and provide context to the translator.

  The `String` is made of two parts, separated by the `|` character. The leading part is the prefix, which must not be translated; the trailing part is the translatable message.

  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 also 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 a version of GNU gettext newer than 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.

  This macro is available since GLib 2.4