2007-11-23 Matthias Clasen <mclasen@redhat.com>
+ * glib/gi18n-lib.h:
+ * glib/gi18n.h: Define a two-argument macro C_() for marking
+ translatable strings with context and implement C_() and Q_()
+ using g_dpgettext(). (#142676, Morten Welinder)
+
+ * glib/glib.symbols:
+ * glib/gstrfuncs.[hc]: Implement g_dpgettext().
+
+2007-11-23 Matthias Clasen <mclasen@redhat.com>
+
* glib/goption.c: Use g_print to print out --help text in
locale encoding. (#469551, Takao Fujiwara)
+2007-11-23 Matthias Clasen <mclasen@redhat.com>
+
+ * glib/tmpl/i18n.sgml:
+ * glib/glib-sections.txt: Add g_dpgettext(), C_()
+
2007-11-18 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/option.sgml: Update the example to demonstrate
<INCLUDE>glib.h,glib/gi18n.h</INCLUDE>
_
Q_
+C_
N_
g_strip_context
+g_dpgettext
<SUBSECTION>
g_get_language_names
</SECTION>
<!-- ##### MACRO Q_ ##### -->
<para>
-Like _(), but applies g_strip_context() to the translation. 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.
</para>
<para>
One use case given in the gettext manual is GUI translation, where one could
language. This could be solved by using "charset|Russian" and
"language|Russian".
</para>
+<para>
+See the C_() macro for a different way to mark up translatable strings
+with context.
+</para>
<note><para>
If you are using the Q_() macro, you need to make sure that you
pass <option>--keyword=Q_</option> to xgettext when extracting messages.
+If you are using GNU gettext >= 0.15, you can also use
+<option>--keyword=Q_:1g</option> to let xgettext split the context
+string off into a msgctxt line in the po file.
</para></note>
@String: the string to be translated, with a '|'-separated prefix which
must not be translated
+@Returns: the translated message
@Since: 2.4
+<!-- ##### MACRO C_ ##### -->
+<para>
+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.
+<informalexample><programlisting>
+label1 = C_("Navigation", "Back");
+label2 = C_("Body part", "Back");
+</programlisting></informalexample>
+</para>
+
+<note><para>
+If you are using the C_() macro, you need to make sure that you
+pass <option>--keyword=C_:1c,2</option> to xgettext when extracting
+messages. Note that this only works with GNU gettext >= 0.15.
+</para></note>
+
+@msgctxt: a message context, must be a string literal
+@msgid: a message id, must be a string literal
+@Returns: the translated message
+@Since: 2.16
+
+
<!-- ##### MACRO N_ ##### -->
<para>
Marks a string for translation, gets replaced with the untranslated string
@Since: 2.4
+
<!-- ##### FUNCTION g_strip_context ##### -->
<para>
#error You must define GETTEXT_PACKAGE before including gi18n-lib.h.
#endif
-#define _(String) dgettext (GETTEXT_PACKAGE, String)
-#define Q_(String) g_strip_context ((String), dgettext (GETTEXT_PACKAGE, String))
-#ifdef gettext_noop
-#define N_(String) gettext_noop (String)
-#else
+#define _(String) dgettext (GETTEXT_PACKAGE, String)
+#define Q_(String) g_dpgettext (GETTEXT_PACKAGE, String, NULL)
#define N_(String) (String)
-#endif
-
-#endif /* __G_I18N_LIB_H__ */
+#define C_(Context,String) g_dpgettext (GETTEXT_PACKAGE, Context "\004" String, String)
+#endif /* __G_I18N_LIB_H__ */
#include <glib/gstrfuncs.h>
#include <libintl.h>
-#define _(String) gettext (String)
-#define Q_(String) g_strip_context ((String), gettext (String))
-#ifdef gettext_noop
-#define N_(String) gettext_noop (String)
-#else
+#define _(String) gettext (String)
+#define Q_(String) g_dpgettext (NULL, String, NULL)
#define N_(String) (String)
-#endif
+#define C_(Context,String) g_dpgettext (NULL, Context "\004" String, String)
+
#endif /* __G_I18N_H__ */
#endif
g_strv_length
g_strip_context
+g_dpgettext
#endif
#endif
#if !defined (HAVE_STRSIGNAL) || !defined(NO_SYS_SIGLIST_DECL)
#include <signal.h>
#endif
+#include <libintl.h>
#include "glib.h"
#include "gprintf.h"
return i;
}
+
+/**
+ * g_dpgettext:
+ * @domain: the translation domain to use, or %NULL to use
+ * the domain set with textdomain()
+ * @msgctxtid: a combined message context and message id
+ * @msgid: the message id, or %NULL
+ *
+ * This function is a variant of dgettext() which supports
+ * a disambiguating message context. GNU gettext uses the
+ * '\004' character to separate the message context and
+ * message id in @msgctxtid. If %NULL is passed as @msgid,
+ * this function also supports the older convention of using
+ * '|' as a separator.
+ *
+ * Applications should normally not use this function directly,
+ * but use the C_() or Q_() macros for translations with
+ * context.
+ *
+ * Returns: The translated string
+ *
+ * Since: 2.16
+ */
+const gchar *
+g_dpgettext (const gchar *domain,
+ const gchar *msgctxtid,
+ const gchar *msgid)
+{
+ const gchar *translation;
+ gchar *sep;
+
+ translation = dgettext (domain, msgctxtid);
+
+ if (translation == msgctxtid)
+ {
+ if (msgid)
+ return msgid;
+
+ sep = strchr (msgctxtid, '|');
+
+ if (sep)
+ {
+ /* try with '\004' instead of '|', in case
+ * xgettext -kQ_:1g was used
+ */
+ gchar *tmp = g_alloca (strlen (msgctxtid) + 1);
+ strcpy (tmp, msgctxtid);
+ tmp[sep - msgctxtid] = '\004';
+
+ translation = dgettext (domain, tmp);
+
+ if (translation == tmp)
+ return sep + 1;
+ }
+ }
+
+ return translation;
+}
+
+
#define __G_STRFUNCS_C__
#include "galiasdef.c"
G_CONST_RETURN gchar *g_strip_context (const gchar *msgid,
const gchar *msgval);
+G_CONST_RETURN gchar *g_dpgettext (const gchar *domain,
+ const gchar *msgctxtid,
+ const gchar *msgid);
+
G_END_DECLS
#endif /* __G_STRFUNCS_H__ */
projects / platform / upstream / glib.git / commitdiff