/src/wrappers/glib/library/utilities/glib_i18n.e

  1deferred class GLIB_I18N
  2--    Internationalization
  3
  4--    Internationalization -- gettext support macros.
  5
  6-- Synopsis
  7
  8
  9--  #include <glib.h>
 10--  #include <glib/gi18n.h>
 11
 12
 13--  #define     _                               (String)
 14--  #define     Q_                              (String)
 15--  #define     N_                              (String)
 16--  const gchar* g_strip_context                (const gchar *msgid,
 17--                                               const gchar *msgval);
 18
 19--  const gchar* const * g_get_language_names   (void);
 20
 21-- Description
 22
 23--    GLib doesn't force any particular localization method upon its users. But since
 24--    GLib itself is localized using the gettext() mechanism, it seems natural to offer
 25--    the de-facto standard gettext() support macros in an easy-to-use form.
 26
 27--    In order to use these macros in an application, you must include glib/gi18n.h.
 28--    For use in a library, must include glib/gi18n-lib.h after defining the
 29--    GETTEXT_PACKAGE macro suitably for your library:
 30
 31--  #define GETTEXT_PACKAGE "gtk20"
 32--  #include <glib/gi18n-lib.h>
 33
 34-- Details
 35
 36--   _()
 37
 38--  #define     _(String)
 39
 40--    Marks a string for translation, gets replaced with the translated string at
 41--    runtime.
 42
 43--    String : the string to be translated
 44
 45--    Since 2.4
 46
 47--    ---------------------------------------------------------------------------------
 48
 49--   Q_()
 50
 51--  #define     Q_(String)
 52
 53--    Like _(), but applies g_strip_context() to the translation. This has the
 54--    advantage that the string can be adorned with a prefix to guarantee uniqueness
 55--    and provide context to the translator.
 56
 57--    One use case given in the gettext manual is GUI translation, where one could e.g.
 58--    disambiguate two "Open" menu entries as "File|Open" and "Printer|Open". Another
 59--    use case is the string "Russian" which may have to be translated differently
 60--    depending on whether it's the name of a character set or a language. This could
 61--    be solved by using "charset|Russian" and "language|Russian".
 62
 63--    String : the string to be translated, with a '|'-separated prefix which must not
 64--             be translated
 65
 66--    Since 2.4
 67
 68--    ---------------------------------------------------------------------------------
 69
 70--   N_()
 71
 72--  #define     N_(String)
 73
 74--    Marks a string for translation, gets replaced with the untranslated string at
 75--    runtime. This is useful in situations where the translated strings can't be
 76--    directly used, e.g. in string array initializers.
 77
 78--       {
 79--         static const char *messages[] = {
 80--           N_("some very meaningful message"),
 81--           N_("and another one")
 82--         };
 83--         const char *string;
 84--         ...
 85--         string
 86--           = index > 1 ? _("a default message") : gettext (messages[index]);
 87
 88--         fputs (string);
 89--         ...
 90--       }
 91
 92--    String : the string to be translated
 93
 94--    Since 2.4
 95
 96--    ---------------------------------------------------------------------------------
 97
 98--   g_strip_context ()
 99
100--  const gchar* g_strip_context                (const gchar *msgid,
101--                                               const gchar *msgval);
102
103--    An auxiliary function for gettext() support (see Q_()).
104
105--    msgid :   a string
106--    msgval :  another string
107--    Returns : msgval, unless msgval is identical to msgid and contains a '|'
108--              character, in which case a pointer to the substring of msgid after the
109--              first '|' character is returned.
110
111--    Since 2.4
112
113--    ---------------------------------------------------------------------------------
114
115--   g_get_language_names ()
116
117--  const gchar* const * g_get_language_names   (void);
118
119--    Computes a list of applicable locale names, which can be used to e.g. construct
120--    locale-dependent filenames or search paths. The returned list is sorted from most
121--    desirable to least desirable and always contains the default locale "C".
122
123--    For example, if LANGUAGE=de:en_US, then the returned list is "de", "en_US", "en",
124--    "C".
125
126--    This function consults the environment variables LANGUAGE, LC_ALL, LC_MESSAGES
127--    and LANG to find the list of locales specified by the user.
128
129--    Returns : a NULL-terminated array of strings owned by GLib that must not be
130--              modified or freed.
131
132--    Since 2.6
133end -- class GLIB_I18N
134