Internationalization
3
LIBXFCE4UTIL Library

# Internationalization

Internationalization and Localization Support Functions

## Synopsis

    #include <libxfce4util/libxfce4util.h>

    void                xfce_textdomain                     (const gchar *package,
                                                             const gchar *localedir,
                                                             const gchar *encoding);
    const gchar*        xfce_strip_context                  (const gchar *msgid,
                                                             const gchar *msgval);
    gchar*              xfce_get_file_localized             (const gchar *filename);
    gchar*              xfce_get_file_localized_r           (gchar *buffer,
                                                             gsize length,
                                                             const gchar *filename);
    gchar*              xfce_get_dir_localized              (const gchar *directory);
    gchar*              xfce_get_dir_localized_r            (gchar *buffer,
                                                             gsize length,
                                                             const gchar *directory);
    gchar*              xfce_get_path_localized             (gchar *dst,
                                                             gsize size,
                                                             const gchar *paths,
                                                             const gchar *filename,
                                                             GFileTest test);
    #define             XFCE_LOCALE_FULL_MATCH
    #define             XFCE_LOCALE_NO_MATCH
    guint               xfce_locale_match                   (const gchar *locale1,
                                                             const gchar *locale2);

## Description

Provides functions to aid application developers making their software localizable. It extends the basic internationalization support provided by GLib 2.4 (and newer). See the GLib Internationalization documentation for the information about the basic functions and macros.

## Details

### xfce_textdomain ()

    void                xfce_textdomain                     (const gchar *package,
                                                             const gchar *localedir,
                                                             const gchar *encoding);

Sets up the translations for `package`.

`package` :

  the package name.

`localedir` :

  the `package`s locale directory.

`encoding` :

  the encoding to use the `package`s translations or `NULL` to use "UTF-8".

### xfce_strip_context ()

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

`xfce_strip_context` has been deprecated since version 4.4 and should not be used in newly-written code. Use `g_strip_context()` instead.

Portable replacement for `g_strip_context()` introduced in GLib 2.4. You prefer this method over `g_strip_context()` cause it allows your software to be used with older versions of GLib as well, though libxfce4util also defines a macro named `g_strip_context()` that simply calls `xfce_strip_context()` if an older GLib version is detected.

`msgid` :

  a string that may be translated.

`msgval` :

  a possible translation for `msgid` or the same as `msgid`.

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 4.2

### xfce_get_file_localized ()

    gchar*              xfce_get_file_localized             (const gchar *filename);

Checks if theres a version of `filename` which is localized to the current locale. This is done by appending the full locale name to `filename`, separated by a '.'. If theres no file of that name, it retries using the full locale name without the encoding (if any), then without the qualifier (if any) and at last the base locale is tried. If all of those fails, a copy of `filename` is returned.

`filename` :

  name of a file to look for a localized version.

Returns :

  path of the localized file or copy of `filename` if no such file exists. Returned string should be freed using `g_free()`.

### xfce_get_file_localized_r ()

    gchar*              xfce_get_file_localized_r           (gchar *buffer,
                                                             gsize length,
                                                             const gchar *filename);

Similar in functionality to `xfce_get_file_localized()`, but stores the result in `buffer` instead of allocating a new buffer.

`buffer` :

  destination buffer to store the localized filename to.

`length` :

  size of `buffer` in bytes.

`filename` :

  name of a file to look for a localized version.

Returns :

  pointer to `buffer` or `NULL` on error.

### xfce_get_dir_localized ()

    gchar*              xfce_get_dir_localized              (const gchar *directory);

Similar to `xfce_get_file_localized()`, but works on directory instead of a file.

`directory` :

  directory name to check for a localized variant.

Returns :

  path of the localized directory name or copy of `directory` if no such directory exists. Returned string should be freed using `g_free()`.

### xfce_get_dir_localized_r ()

    gchar*              xfce_get_dir_localized_r            (gchar *buffer,
                                                             gsize length,
                                                             const gchar *directory);

Similar to xfce_get_file_localized_r, but works on directory instead of regular file.

`buffer` :

  destination buffer to store the localized filename to.

`length` :

  size of `buffer` in bytes.

`directory` :

  name of directory to check for localized variant of.

Returns :

  pointer to `buffer` or `NULL` on error.

### xfce_get_path_localized ()

    gchar*              xfce_get_path_localized             (gchar *dst,
                                                             gsize size,
                                                             const gchar *paths,
                                                             const gchar *filename,
                                                             GFileTest test);

`paths` is a ':'-separated list of pathnames.

`F` - The `filename` `L` - The language string, as returned by setlocale(LC_MESSAGES, NULL) `l` - The language component of the language string `N` - application name

Example paths:

/usr/local/lib/`L`/`F`:/usr/local/share/`N`/`l`/`F`

`dst` :

  destination buffer.

`size` :

  size of `dst` in bytes.

`paths` :

`filename` :

`test` :

Returns :

### XFCE_LOCALE_FULL_MATCH

    #define XFCE_LOCALE_FULL_MATCH 50

Returned by xfce_locale_match in case of a full match.

### XFCE_LOCALE_NO_MATCH

    #define XFCE_LOCALE_NO_MATCH    0

Returned by xfce_locale_match if no match could be detected.

### xfce_locale_match ()

    guint               xfce_locale_match                   (const gchar *locale1,
                                                             const gchar *locale2);

The locale is of the general form LANG_COUNTRY.ENCODING @ MODIFIER, where each of COUNTRY, ENCODING and MODIFIER can be absent.

The match is done by actually removing the rightmost element one by one. This is not entirely according to the freedesktop.org specification, but much easier. Will probably be fixed in the future.

`locale1` :

  the current locale value as returned by setlocale(LC_MESSAGES,`NULL`).

`locale2` :

  the locale value to match against.

Returns :

  an integer value indicating the level of matching, where the constant XFCE_LOCALE_FULL_MATCH indicates a full match and XFCE_LOCALE_NO_MATCH means no match. Every other value indicates a partial match, the higher the value, the better the match. You should not rely on any specific value besides the constants XFCE_LOCALE_FULL_MATCH and XFCE_LOCALE_NO_MATCH, since the range of returned values may change in the future.

Since 4.2

## See Also

GLib Internationalization