Gnome Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# gnome-i18n

## Name

gnome-i18n -- Support for localization and internationalization.

## Synopsis

    #include <gnome.h>

    #define     _                               (String)
    #define     N_                              (String)
    #define     textdomain                      (String)
    #define     gettext                         (String)
    #define     dgettext                        (Domain,Message)
    #define     dcgettext                       (Domain,Message,Type)
    #define     bindtextdomain                  (Domain,Directory)
    const char* gnome_i18n_get_language         (void);
    GList*      gnome_i18n_get_language_list    (const gchar *category_name);
    void        gnome_i18n_set_preferred_language
                                                (const char *val);
    const char* gnome_i18n_get_preferred_language
                                                (void);
    void        gnome_i18n_init                 (void);

## Description

This module allows the programmer to internationalize his application by providing a number of macros that can be used to tag his texts, and some functions that control the internationalization of the application or library.

Typically the programmer would enclose text strings that are displayed to the user in a _() macro call. This macro serves two purposes: it is used to tag the string for translation (it is a special sequence recognized by the GNU gettext framework) and it is used at run-time to invoke the translation process on the current string.

Example 1. Typical usage of the _ macro

    void print_hello (void)
    {
            printf (_("Hello World"));
    }

The macro _() can map to either an invocation to gettext (which means that the string argument is translated in the default application translation domain) or to dgettext (which means that the string is translated into the GNOME_EXPLICIT_TRANSLATION_DOMAIN.

Typically applications will just include the `gnome.h` header file, the `libgnome.h` or the `gnome-i18n.h` header file and this will define the _() macro as an invocation to gettext(). In the case of libraries, shared object modules (dynamically linked libraries) or shared object CORBA servers (CORBA servers implemented as shared libraries), you should define the GNOME_EXPLICIT_TRANSLATION_DOMAIN macro to your package name (usually a define in the compilation Makefile or in the config.h file will do it). By doing this your library, shared library or CORBA server will explicitly translate its string messages in its own translation domain (rather than using the application domain, which will not have a translation table for your messages).

All of the functions in this module do either map to an empty action if the ENABLE_NLS macro is not defined or to actual functions if it is defined.

See the Info page for GNU gettext to learn more on the internationalization process for an application.

## Details

### _()

    #define     _(String)

Use this to tag strings in an executable path, this macro expands to gettext() or dgettext() if the application supports internationalization.

`String` : |

### N_()

    #define     N_(String)

This macro is just an identity macro, the only purpose of this macro is to allow `gettext` to identify the string as a translatable message. This macro can be used in static initializers, where the _() macros can not be used.

Example 2. Typical usage of the N_ macro

    char *days [5] = {
        	N_("monday"),
        	N_("tuesday"),
        	N_("wednesday"),
        	N_("thursday"),
        	N_("friday")
    };

    void print_days (void)
    {
            int i;

            for (i = 0; i < 5; i++)
                 printf (_("The day of the week s is"), _(days [i]));
    }

`String` : |

### textdomain()

    #    define textdomain(String) (String)

`String` : |

### gettext()

    #    define gettext(String) (String)

`String` : |

### dgettext()

    #    define dgettext(Domain,Message) (Message)

`Domain` : |
`Message` : |

### dcgettext()

    #    define dcgettext(Domain,Message,Type) (Message)

`Domain` : |
`Message` : |
`Type` : |

### bindtextdomain()

    #    define bindtextdomain(Domain,Directory) (Domain)

`Domain` : |
`Directory` : |

### gnome_i18n_get_language ()

    const char* gnome_i18n_get_language         (void);

Returns current language (contents of "LANG" environment variable).

Returns : |

### gnome_i18n_get_language_list ()

    GList*      gnome_i18n_get_language_list    (const gchar *category_name);

This computes a list of language strings. It searches in the standard environment variables to find the list, which is sorted in order from most desirable to least desirable. The `C' locale is appended to the list if it does not already appear. If `category_name` is `NULL`, then LC_ALL is assumed.

`category_name` : | Name of category to look up, e.g. "LC_MESSAGES".
Returns : | the list of languages

### gnome_i18n_set_preferred_language ()

    void        gnome_i18n_set_preferred_language
                                                (const char *val);

This sets the user's preferred language in the Gnome config database. This value can always be overridden by the standard environment variables. It exists so that a config applet which chooses the preferred language has a standard place to put the resulting information.

`val` : | Preferred language

### gnome_i18n_get_preferred_language ()

    const char* gnome_i18n_get_preferred_language
                                                (void);

Returns : | the preferred language as set in the Gnome config database.

### gnome_i18n_init ()

    void        gnome_i18n_init                 (void);

Initialize the i18n environment variables (if not already set) from the Gnome config database. Ordinarily this should not be called by user code.

## See Also

GNU gettext info page

<<< Previous Page | Home | Up | Next Page >>>
gnome-history | gnome-metadata