Ticket #9988: pgettext-2.patch

django/core/management/commands/makemessages.py

@@ -190 +190 @@
                     f.write(src)
                 finally:
                     f.close()
-                cmd = 'xgettext -d %s -L Perl --keyword=gettext_noop --keyword=gettext_lazy --keyword=ngettext_lazy:1,2 --from-code UTF-8 -o - "%s"' % (domain, os.path.join(dirpath, thefile))
+                cmd = 'xgettext -d %s -L Perl --keyword=gettext_noop --keyword=gettext_lazy --keyword=ngettext_lazy:1,2 --keyword=pgettext:1c,2 --keyword=npgettext:1c,2,3 --from-code UTF-8 -o - "%s"' % (domain, os.path.join(dirpath, thefile))
                 msgs, errors = _popen(cmd)
                 if errors:
                     raise CommandError("errors happened while running xgettext on %s\n%s" % (file, errors))
@@ -225 +225 @@
                         raise SyntaxError(msg)
                 if verbosity > 1:
                     sys.stdout.write('processing file %s in %s\n' % (file, dirpath))
-                cmd = 'xgettext -d %s -L Python --keyword=gettext_noop --keyword=gettext_lazy --keyword=ngettext_lazy:1,2 --keyword=ugettext_noop --keyword=ugettext_lazy --keyword=ungettext_lazy:1,2 --from-code UTF-8 -o - "%s"' % (
+                cmd = 'xgettext -d %s -L Python --keyword=gettext_noop --keyword=gettext_lazy --keyword=ngettext_lazy:1,2 --keyword=ugettext_noop --keyword=ugettext_lazy --keyword=ungettext_lazy:1,2 --keyword=pgettext:1c,2 --keyword=npgettext:1c,2,3 --keyword=pgettext_lazy:1c,2 --keyword=npgettext_lazy:1c,2,3 --from-code UTF-8 -o - "%s"' % (
                     domain, os.path.join(dirpath, thefile))
                 msgs, errors = _popen(cmd)
                 if errors:

django/views/i18n.py

@@ -68 +68 @@
 function gettext(msgid) { return msgid; }
 function ngettext(singular, plural, count) { return (count == 1) ? singular : plural; }
 function gettext_noop(msgid) { return msgid; }
+function pgettext(context, msgid) { return msgid; }
+function npgettext(context, singular, plural, count) { return (count == 1) ? singular : plural; }
 """
 
 LibHead = """
@@ -98 +100 @@
 
 function gettext_noop(msgid) { return msgid; }
 
+function pgettext(context, msgid) {
+  var value = gettext(context + '\x04' + msgid);
+  if (value.indexOf('\x04') != -1) {
+    value = msgid;
+  }
+  return value;
+}
+
+function npgettext(context, singular, plural, count) {
+  var value = ngettext(context + '\x04' + singular, context + '\x04' + plural, count);
+  if (value.indexOf('\x04') != -1) {
+    value = ngettext(singular, plural, count);
+  }
+  return value;
+}
 """
 
 LibFormatHead = """

django/utils/translation/trans_real.py

@@ -279 +279 @@
 def ugettext(message):
     return do_translate(message, 'ugettext')
 
+def pgettext(context, message):
+    # \x04 is a magic gettext number to separate context from message
+    result = do_translate(u"%s\x04%s" % (context, message), 'ugettext')
+    if "\x04" in result:
+        # Translation not found
+        result = message
+    return result
+
 def gettext_noop(message):
     """
     Marks strings for translation but doesn't translate them now. This can be
@@ -313 +321 @@
     """
     return do_ntranslate(singular, plural, number, 'ungettext')
 
+def npgettext(context, singular, plural, number):
+    # \x04 is a magic gettext number to separate context from message
+    result = do_ntranslate(u"%s\x04%s" % (context, singular),
+                           u"%s\x04%s" % (context, plural), number, 'ungettext')
+    if "\x04" in result:
+        # Translation not found
+        result = do_ntranslate(singular, plural, number, 'ungettext')
+    return result
+
 def check_for_language(lang_code):
     """
     Checks whether there is a global language file for the given language

django/utils/translation/__init__.py

@@ -10 +10 @@
         'get_language', 'get_language_bidi', 'get_date_formats',
         'get_partial_date_formats', 'check_for_language', 'to_locale',
         'get_language_from_request', 'templatize', 'ugettext', 'ugettext_lazy',
-        'ungettext', 'deactivate_all']
+        'ungettext', 'ungettext_lazy', 'pgettext', 'pgettext_lazy',
+        'npgettext', 'npgettext_lazy', 'deactivate_all']
 
 # Here be dragons, so a short explanation of the logic won't hurt:
 # We are trying to solve two problems: (1) access settings, in particular
@@ -63 +64 @@
 def ungettext(singular, plural, number):
     return _trans.ungettext(singular, plural, number)
 
+def pgettext(context, message):
+    return _trans.pgettext(context, message)
+
+def npgettext(context, singular, plural, number):
+    return _trans.npgettext(context, singular, plural, number)
+
 ngettext_lazy = lazy(ngettext, str)
 gettext_lazy = lazy(gettext, str)
 ungettext_lazy = lazy(ungettext, unicode)
 ugettext_lazy = lazy(ugettext, unicode)
+pgettext_lazy = lazy(pgettext, unicode)
+npgettext_lazy = lazy(npgettext, unicode)
 
 def activate(language):
     return _trans.activate(language)

django/utils/translation/trans_null.py

@@ -15 +15 @@
 def ungettext(singular, plural, number):
     return force_unicode(ngettext(singular, plural, number))
 
+def pgettext(context, message):
+    return ugettext(message)
+
+def npgettext(context, singular, plural, number):
+    return ungettext(singular, plural, number)
+
 activate = lambda x: None
 deactivate = deactivate_all = lambda: None
 get_language = lambda: settings.LANGUAGE_CODE

tests/regressiontests/views/locale/fr/LC_MESSAGES/djangojs.po

@@ -22 +22 @@
 
 msgid "Choose a time"
 msgstr "Choisir une heure"
+
+msgctxt "month name"
+msgid "May"
+msgstr "mai"

tests/regressiontests/views/tests/i18n.py

@@ -30 +30 @@
             # catalog['this is to be translated'] = 'same_that_trans_txt'
             # javascript_quote is used to be able to check unicode strings
             self.assertContains(response, javascript_quote(trans_txt), 1)
+            if lang_code == 'fr':
+                # Message with context (msgctxt)
+                self.assertContains(response, "['month name\x04May'] = 'mai';", 1)
 
 
 class JsI18NTests(TestCase):

tests/regressiontests/i18n/other/locale/de/LC_MESSAGES/django.po

@@ -20 +20 @@
 #: models.py:3
 msgid "Date/time"
 msgstr "Datum/Zeit (LOCALE_PATHS)"
+
+#: models.py:5
+msgctxt "month name"
+msgid "May"
+msgstr "Mai"
+
+#: models.py:7
+msgctxt "verb"
+msgid "May"
+msgstr "Kann"
+
+#: models.py:9
+msgctxt "search"
+msgid "%d result"
+msgid_plural "%d results"
+msgstr[0] "%d Resultat"
+msgstr[1] "%d Resultate"

tests/regressiontests/i18n/tests.py

@@ -11 +11 @@
 from django.utils.formats import get_format, date_format, time_format, localize, localize_input, iter_format_modules
 from django.utils.numberformat import format as nformat
 from django.utils.safestring import mark_safe, SafeString, SafeUnicode
-from django.utils.translation import ugettext, ugettext_lazy, activate, deactivate, gettext_lazy, to_locale
+from django.utils.translation import ugettext, ugettext_lazy, activate, deactivate, gettext_lazy, pgettext, npgettext, to_locale
 from django.utils.importlib import import_module
 
 
@@ -54 +54 @@
         s2 = pickle.loads(pickle.dumps(s1))
         self.assertEqual(unicode(s2), "test")
 
+    def test_pgettext(self):
+        # Reset translation catalog to include other/locale/de
+        self.old_locale_paths = settings.LOCALE_PATHS
+        settings.LOCALE_PATHS += (os.path.join(os.path.dirname(os.path.abspath(__file__)), 'other', 'locale'),)
+        from django.utils.translation import trans_real
+        trans_real._active = {}
+        trans_real._translations = {}
+        activate('de')
+
+        self.assertEqual(pgettext("unexisting", "May"), u"May")
+        self.assertEqual(pgettext("month name", "May"), u"Mai")
+        self.assertEqual(pgettext("verb", "May"), u"Kann")
+        self.assertEqual(npgettext("search", "%d result", "%d results", 4) % 4, u"4 Resultate")
+
+        settings.LOCALE_PATHS = self.old_locale_paths
+
     def test_string_concat(self):
         """
         unicode(string_concat(...)) should not raise a TypeError - #4796

docs/topics/i18n/internationalization.txt

@@ -193 +193 @@
     ``django-admin.py compilemessages`` or a ``KeyError`` Python exception at
     runtime.
 
+.. _contextual-markers:
+
+Contextual markers
+------------------
+
+.. versionadded:: 1.3
+
+In certain cases, English words may have several meanings, such as ``"May"``
+which can refer to a month name or to a verb. If this same word is then used in
+the code with both meanings, the translator cannot translate it two times
+differently. To be able to disambiguate such strings, you can use the 
+``django.utils.translation.pgettext()`` function, or the 
+``django.utils.translation.npgettext()`` function if the string needs
+pluralization.
+
+In the resulting .po file, the string will then appear as often as there are
+different contextual markers for the same string (the context will appear on the 
+``msgctxt`` line), allowing the translator to give a different translation for
+each of them.
+
+For example:
+
+    from django.utils.translation import pgettext
+
+    month = pgettext("month name", "May")
+
+which will appear in the .po file as:
+
+    msgctxt "month name"
+    msgid "May"
+    msgstr ""
+
 .. _lazy-translations:
 
 Lazy translation

docs/releases/1.3.txt

@@ -86 +86 @@
 
 For more information, see :ref:`transaction-management-functions`.
 
+Contextual markers in translatable strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a single English word or string appear in your code with different meanings,
+you can now use the ``pgettext`` function to specify the context of the string.
+
+For more information, see :ref:`contextual-markers`
+
 Everything else
 ~~~~~~~~~~~~~~~