GLib Reference Manual | ||||
---|---|---|---|---|
Top | Description |
#include <glib.h> #include <glib/gi18n.h> #define _ (String) #define Q_ (String) #define C_ (Context, String) #define N_ (String) #define NC_ (Context, String) const gchar * g_dgettext (const gchar *domain
,const gchar *msgid
); const gchar * g_dcgettext (const gchar *domain
,const gchar *msgid
,int category
); const gchar * g_dngettext (const gchar *domain
,const gchar *msgid
,const gchar *msgid_plural
,gulong n
); const gchar * g_dpgettext (const gchar *domain
,const gchar *msgctxtid
,gsize msgidoffset
); const gchar * g_dpgettext2 (const gchar *domain
,const gchar *context
,const gchar *msgid
); const gchar * g_strip_context (const gchar *msgid
,const gchar *msgval
); const gchar * const * g_get_language_names (void
); gchar ** g_get_locale_variants (const gchar *locale
);
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, 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> |
Note that you also have to call setlocale()
and textdomain()
(as well as
bindtextdomain()
and bind_textdomain_codeset()
) early on in your main()
to make gettext()
work.
The gettext manual covers details of how to set up message extraction
with xgettext.
#define _(String)
Marks a string for translation, gets replaced with the translated string at runtime.
|
the string to be translated |
Since 2.4
#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.
|
the string to be translated, with a '|'-separated prefix which must not be translated |
Returns : |
the translated message |
Since 2.4
#define C_(Context,String)
Uses gettext to get the translation for msgid
. msgctxt
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.
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.
|
a message context, must be a string literal |
|
a message id, must be a string literal |
Returns : |
the translated message |
Since 2.16
#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); ... } |
|
the string to be translated |
Since 2.4
#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 |
{ 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.
|
a message context, must be a string literal |
|
a message id, must be a string literal |
Since 2.18
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
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.
|
the translation domain to use, or NULL to use
the domain set with textdomain()
|
|
message to translate |
Returns : |
The translated string |
Since 2.18
const gchar * g_dcgettext (const gchar *domain
,const gchar *msgid
,int 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.
|
the translation domain to use, or NULL to use
the domain set with textdomain() . [allow-none]
|
|
message to translate |
|
a locale category |
Returns : |
the translated string for the given locale category |
Since 2.26
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.
|
the translation domain to use, or NULL to use
the domain set with textdomain()
|
|
message to translate |
|
plural form of the message |
|
the quantity for which translation is needed |
Returns : |
The translated string |
Since 2.18
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.
|
the translation domain to use, or NULL to use
the domain set with textdomain()
|
|
a combined message context and message id, separated by a \004 character |
|
the offset of the message id in msgctxid
|
Returns : |
The translated string |
Since 2.16
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.
|
the translation domain to use, or NULL to use
the domain set with textdomain()
|
|
the message context |
|
the message |
Returns : |
The translated string |
Since 2.18
const gchar * g_strip_context (const gchar *msgid
,const gchar *msgval
);
An auxiliary function for gettext()
support (see Q_()
).
|
a string |
|
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
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
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()
.
|
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