Fixed #9988 -- Added support for translation contexts. Thanks, Claude Paroz.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14450 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/releases/1.3.txt

@@ -86,6 +86,14 @@ Users of Python 2.5 and above may now use :ref:`transaction management functions
 
 For more information, see :ref:`transaction-management-functions`.
 
+Contextual markers in translatable strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For translation strings with ambiguous meaning, you can now
+use the ``pgettext`` function to specify the context of the string.
+
+For more information, see :ref:`contextual-markers`
+
 Everything else
 ~~~~~~~~~~~~~~~
 

docs/topics/i18n/internationalization.txt

@@ -193,6 +193,39 @@ cardinality of the elements at play.
     ``django-admin.py compilemessages`` or a ``KeyError`` Python exception at
     runtime.
 
+.. _contextual-markers:
+
+Contextual markers
+------------------
+
+.. versionadded:: 1.3
+
+Sometimes words have several meanings, such as ``"May"`` in English, which
+refers to a month name and to a verb. To enable translators to translate
+these words correctly in different contexts, you can use the
+``django.utils.translation.pgettext()`` function, or the
+``django.utils.translation.npgettext()`` function if the string needs
+pluralization. Both take a context string as the first variable.
+
+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")
+
+will appear in the .po file as:
+
+.. code-block:: po
+
+    msgctxt "month name"
+    msgid "May"
+    msgstr ""
+
 .. _lazy-translations:
 
 Lazy translation