* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
#include "config.h"
#include "ggettext.h"
+#include "glibintl.h"
+#include "glib-private.h"
#include "galloca.h"
#include "gthread.h"
* This is an internal function and should only be used by
* the internals of glib (such as libgio).
*
- * Returns: the transation of @str to the current locale
+ * Returns: the translation of @str to the current locale
*/
const gchar *
glib_pgettext (const gchar *msgctxtid,
*
* An auxiliary function for gettext() support (see Q_()).
*
- * Return value: @msgval, unless @msgval is identical to @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.
*
/**
* g_dpgettext:
- * @domain: the translation domain to use, or %NULL to use
+ * @domain: (allow-none): the translation domain to use, or %NULL to use
* the domain set with textdomain()
* @msgctxtid: a combined message context and message id, separated
* by a \004 character
*/
/**
* g_dpgettext2:
- * @domain: the translation domain to use, or %NULL to use
+ * @domain: (allow-none): the translation domain to use, or %NULL to use
* the domain set with textdomain()
* @context: the message context
* @msgid: the message
* - If locale is "C", maybe user calls setlocale(LC_ALL,"") later.
* Continue with old behavior of translating.
*/
- if (0 != strcmp (default_domain, "messages") &&
+ if (!default_domain || !translator_comment || !translate_locale ||
+ (0 != strcmp (default_domain, "messages") &&
'\0' == *translator_comment &&
0 != strncmp (translate_locale, "en_", 3) &&
- 0 != strcmp (translate_locale, "C"))
+ 0 != strcmp (translate_locale, "C")))
should_translate = FALSE;
g_once_init_leave (&translate,
/**
* g_dgettext:
- * @domain: the translation domain to use, or %NULL to use
+ * @domain: (allow-none): the translation domain to use, or %NULL to use
* the domain set with textdomain()
* @msgid: message to translate
*
*
* This function disables translations if and only if upon its first
* call all the following conditions hold:
- * <itemizedlist>
- * <listitem>@domain is not %NULL</listitem>
- * <listitem>textdomain() has been called to set a default text domain</listitem>
- * <listitem>there is no translations available for the default text domain
- * and the current locale</listitem>
- * <listitem>current locale is not "C" or any English locales (those
- * starting with "en_")</listitem>
- * </itemizedlist>
+ *
+ * - @domain is not %NULL
+ *
+ * - textdomain() has been called to set a default text domain
+ *
+ * - there is no translations available for the default text domain
+ * and the current locale
+ *
+ * - current locale is not "C" or any English locales (those
+ * starting with "en_")
*
* 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
+ * 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,
* @category: a locale category
*
* This is a variant of g_dgettext() that allows specifying a locale
- * category instead of always using %LC_MESSAGES. See g_dgettext() for
+ * category instead of always using `LC_MESSAGES`. See g_dgettext() for
* more information about how this functions differs from calling
* dcgettext() directly.
*
/**
* g_dngettext:
- * @domain: the translation domain to use, or %NULL to use
+ * @domain: (allow-none): the translation domain to use, or %NULL to use
* the domain set with textdomain()
* @msgid: message to translate
* @msgid_plural: plural form of the message
return dngettext (domain, msgid, msgid_plural, n);
}
+
+
+/**
+ * SECTION:i18n
+ * @title: Internationalization
+ * @short_description: gettext support macros
+ * @see_also: the gettext manual
+ *
+ * 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, you must include
+ * `<glib/gi18n-lib.h>`
+ * after defining the %GETTEXT_PACKAGE macro suitably for your library:
+ * |[<!-- language="C" -->
+ * #define GETTEXT_PACKAGE "gtk20"
+ * #include <glib/gi18n-lib.h>
+ * ]|
+ * For an application, note that you also have to call bindtextdomain(),
+ * bind_textdomain_codeset(), textdomain() and setlocale() early on in your
+ * main() to make gettext() work.
+ *
+ * For a library, you only have to call bindtextdomain() and
+ * bind_textdomain_codeset() in your initialization function. If your library
+ * doesn't have an initialization function, you can call the functions before
+ * the first translated message.
+ *
+ * The gettext manual covers details of how to set up message extraction
+ * with xgettext.
+ */
+
+/**
+ * _:
+ * @String: the string to be translated
+ *
+ * Marks a string for translation, gets replaced with the translated string
+ * at runtime.
+ *
+ * Since: 2.4
+ */
+
+/**
+ * Q_:
+ * @String: the string to be translated, with a '|'-separated prefix
+ * which must not be translated
+ *
+ * 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.
+ *
+ * Returns: the translated message
+ *
+ * Since: 2.4
+ */
+
+/**
+ * C_:
+ * @Context: a message context, must be a string literal
+ * @String: a message id, must be a string literal
+ *
+ * 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.
+ * |[<!-- language="C" -->
+ * 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.
+ *
+ * Returns: the translated message
+ *
+ * Since: 2.16
+ */
+
+/**
+ * N_:
+ * @String: the string to be translated
+ *
+ * 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.
+ * |[<!-- language="C" -->
+ * {
+ * 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);
+ * ...
+ * }
+ * ]|
+ *
+ * Since: 2.4
+ */
+
+/**
+ * NC_:
+ * @Context: a message context, must be a string literal
+ * @String: a message id, must be a string literal
+ *
+ * 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.
+ *
+ * |[<!-- language="C" -->
+ * {
+ * 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.
+ *
+ * Since: 2.18
+ */
+