Define a two-argument macro C_() for marking translatable strings with

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().


svn path=/trunk/; revision=5917

ChangeLog

@@ -1,3 +1,13 @@
+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 

docs/reference/ChangeLog

@@ -1,3 +1,8 @@
+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

docs/reference/glib/glib-sections.txt

@@ -2483,8 +2483,10 @@ g_unichar_to_utf8
 <INCLUDE>glib.h,glib/gi18n.h</INCLUDE>
 _
 Q_
+C_
 N_
 g_strip_context
+g_dpgettext
 <SUBSECTION>
 g_get_language_names
 </SECTION>

docs/reference/glib/tmpl/i18n.sgml

@@ -44,9 +44,9 @@ at runtime.
 
 <!-- ##### MACRO Q_ ##### -->
 <para>
-Like _(), but applies g_strip_context() to the translation. This has the
+Like _(), but handles context in message ids. This has the advantage that 
-advantage that the string can be adorned with a prefix to guarantee 
+the string can be adorned with a prefix to guarantee uniqueness and provide 
-uniqueness and provide context to the translator.
+context to the translator. 
 </para>
 <para>
 One use case given in the gettext manual is GUI translation, where one could 
@@ -56,16 +56,48 @@ 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".
 </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
@@ -92,6 +124,7 @@ be directly used, e.g. in string array initializers.
 @Since: 2.4
 
 
+
 <!-- ##### FUNCTION g_strip_context ##### -->
 <para>
 

glib/gi18n-lib.h

@@ -27,14 +27,10 @@
 #error You must define GETTEXT_PACKAGE before including gi18n-lib.h.
 #endif
 
-#define _(String) dgettext (GETTEXT_PACKAGE, String)
+#define  _(String) dgettext (GETTEXT_PACKAGE, String)
-#define Q_(String) g_strip_context ((String), dgettext (GETTEXT_PACKAGE, String))
+#define Q_(String) g_dpgettext (GETTEXT_PACKAGE, String, NULL)
-#ifdef gettext_noop
-#define N_(String) gettext_noop (String)
-#else
 #define N_(String) (String)
-#endif
+#define C_(Context,String) g_dpgettext (GETTEXT_PACKAGE, Context "\004" String, String)
+
 
 #endif  /* __G_I18N_LIB_H__ */
-
-

glib/gi18n.h

@@ -22,13 +22,11 @@
 #include <glib/gstrfuncs.h>
 #include <libintl.h>
 
-#define _(String) gettext (String)
+#define  _(String) gettext (String)
-#define Q_(String) g_strip_context ((String), gettext (String))
+#define Q_(String) g_dpgettext (NULL, String, NULL)
-#ifdef gettext_noop
-#define N_(String) gettext_noop (String)
-#else
 #define N_(String) (String)
-#endif
+#define C_(Context,String) g_dpgettext (NULL, Context "\004" String, String)
+
 
 #endif  /* __G_I18N_H__ */
 

glib/glib.symbols

@@ -1121,6 +1121,7 @@ g_strdown
 #endif
 g_strv_length
 g_strip_context
+g_dpgettext
 #endif
 #endif
 

glib/gstrfuncs.c

@@ -42,6 +42,7 @@
 #if !defined (HAVE_STRSIGNAL) || !defined(NO_SYS_SIGLIST_DECL)
 #include <signal.h>
 #endif
+#include <libintl.h>
 
 #include "glib.h"
 #include "gprintf.h"
@@ -2843,5 +2844,65 @@ g_strv_length (gchar **str_array)
   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"

glib/gstrfuncs.h

@@ -243,6 +243,10 @@ gchar*                g_stpcpy         (gchar        *dest,
 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__ */