|
+ |
|
|
GLib Reference Manual | @@ -46,7 +26,7 @@ Description
|---|
| @@ -55,35 +35,42 @@ |
#include <glib.h> #include <glib/gi18n.h> +#define _ (String) #define Q_ (String) -#define C_ (Context,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_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); +#define NC_ (Context, + String) +const gchar * g_dgettext (const gchar *domain, +const gchar *msgid); +const gchar * g_dcgettext (const gchar *domain, +const gchar *msgid, +gint 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); +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.
@@ -97,202 +84,290 @@ In order to use these macros in an application, you must include
glib/gi18n-lib.h after defining
the GETTEXT_PACKAGE macro suitably for your library:
-#define GETTEXT_PACKAGE "gtk20" -#include <glib/gi18n-lib.h> -
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.
+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". +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.
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 - | +the string to be translated, with a '|'-separated prefix +which must not be translated |
Returns : |
-the translated message - | +the translated message |
Since 2.4
#define C_(Context,String)
-Uses gettext to get the translation for msgid. msgctxt is
+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.
-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. Note that this only works with GNU gettext >= 0.15.
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 context, must be a string literal |
|
-a message id, must be a string literal - | +a message id, must be a string literal |
Returns : |
-the translated message - | +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.
-
- {
- 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]);
+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);
- ...
- }
-
+ fputs (string);
+ ...
+}
+
+
+
+
+
+
String :
the string to be translated
-
+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.
-
- {
- 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]);
+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
+14
{
+ 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);
+ ...
+}
+
+
+
- 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.
+
+
+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 context, must be a string literal |
|
-a message id, 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);+
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
@@ -332,38 +407,73 @@ cases the application should call textdomain() aft
Applications should normally not use this function directly,
-but use the _() macro for translations.
_() macro for translations.
+
|
- the translation domain to use, or NULL to use
- the domain set with textdomain()
+ | the translation domain to use, or NULL to use
+the domain set with textdomain(). [allow-none]
|
|
-message to translate - | +message to translate |
Returns : |
-The translated string - - | +The translated string |
Since 2.18
const gchar * g_dcgettext (+const gchar *domain, +const gchar *msgid, +gint 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);+
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
@@ -371,47 +481,43 @@ 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()
+ | the translation domain to use, or NULL to use
+the domain set with textdomain(). [allow-none]
|
|
-message to translate - | +message to translate |
|
-plural form of the message - | +plural form of the message |
|
-the quantity for which translation is needed - | +the quantity for which translation is needed |
Returns : |
-The translated string - - | +The translated string |
Since 2.18
const gchar * g_dpgettext (const gchar *domain, - const gchar *msgctxtid, - gsize msgidoffset);+
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
@@ -422,48 +528,46 @@ trying to use the deprecated convention of using "|" as a separation
character.
-This uses g_dgettext() internally. See that functions for differences
+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.
C_() macro for translations with context.
+
|
- the translation domain to use, or NULL to use
- the domain set with textdomain()
+ | the translation domain to use, or NULL to use
+the domain set with textdomain(). [allow-none]
|
|
-a combined message context and message id, separated - by a \004 character - | +a combined message context and message id, separated +by a \004 character |
|
- the offset of the message id in msgctxid
+ | the offset of the message id in msgctxid
|
Returns : |
-The translated string - - | +The translated string |
Since 2.16
const gchar * g_dpgettext2 (const gchar *domain, - const gchar *context, - const gchar *msgid);+
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
@@ -471,81 +575,76 @@ a disambiguating message context. GNU gettext uses the
message id in msgctxtid.
-This uses g_dgettext() internally. See that functions for differences
+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.
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 translation domain to use, or NULL to use
+the domain set with textdomain(). [allow-none]
|
|
-the message context - | +the message context |
|
-the message - | +the message |
Returns : |
-The translated string - - | +The translated string |
Since 2.18
const gchar * g_strip_context (const gchar *msgid, - const gchar *msgval);+
const gchar * g_strip_context (const gchar *msgid, +const gchar *msgval);
-An auxiliary function for gettext() support (see Q_()).
gettext() support (see Q_()).
+
|
-a string - | +a string |
|
-another 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.
-
- |
+
+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);+
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 +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".
@@ -553,31 +652,65 @@ 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.
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.
-
+ | 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".
+
-The gettext manual.
+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
+