Ticket #10004: comment-extraction-3.patch

django/core/management/commands/makemessages.py

@@ -196 +196 @@
                     'xgettext -d %s -L Perl %s --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"' % (
+                    '--from-code UTF-8 --add-comments=L10n -o - "%s"' % (
                         domain, wrap, os.path.join(dirpath, thefile)
                     )
                 )
@@ -240 +240 @@
                     '--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, wrap, os.path.join(dirpath, thefile))
+                    '--keyword=npgettext_lazy:1c,2,3 --from-code UTF-8 '
+                    '--add-comments=L10n -o - "%s"' % (
+                        domain, wrap, os.path.join(dirpath, thefile))
                 )
                 msgs, errors = _popen(cmd)
                 if errors:

tests/regressiontests/i18n/commands/__init__.py

@@ +1 @@
+from django.utils.translation import ugettext as _
+
+# L10n: This comment should be extracted
+dummy1 = _("This is a translatable string.")
+
+# This comment should not be extracted
+dummy2 = _("This is another translatable string.")
+

tests/regressiontests/i18n/commands/extraction.py

@@ -38 +38 @@
         return self.assert_(not re.search('^msgid %s' % msgid, s, re.MULTILINE))
 
 
-class TemplateExtractorTests(ExtractorTests):
+class BasicExtractorTests(ExtractorTests):
 
+    def test_comments_extractor(self):
+        os.chdir(self.test_dir)
+        management.call_command('makemessages', locale=LOCALE, verbosity=0)
+        self.assert_(os.path.exists(self.PO_FILE))
+        po_contents = open(self.PO_FILE, 'r').read()
+        self.assert_('#. L10n: This comment should be extracted' in po_contents)
+        self.assert_('This comment should not be extracted' not in po_contents)
+
     def test_templatize(self):
         os.chdir(self.test_dir)
         management.call_command('makemessages', locale=LOCALE, verbosity=0)

docs/topics/i18n/internationalization.txt

@@ -100 +100 @@
 have more than a single parameter. If you used positional interpolation,
 translations wouldn't be able to reorder placeholder text.
 
+.. _translator-comments:
+
+Comments for translators
+------------------------
+
+.. versionadded:: 1.3
+
+If you would like to give translators any hint about a translatable string, you
+can add a comment prefixed with the ``L10n`` keyword on the line just before the
+string marked for translation:
+
+    def my_view(request):
+        # L10n: This message appears on the home page only
+        output = ugettext("Welcome to my site.")
+
+The comment will then appear in the resulting .po file and should also be
+displayed by most translation tools.
+
 Marking strings as no-op
 ------------------------
 

docs/releases/1.3.txt

@@ -86 +86 @@
 
 For more information, see :ref:`transaction-management-functions`.
 
-Contextual markers in translatable strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Contextual markers and comments for 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`
+And if you just want to add some information aimed at translators, you
+can also add special translator comments in the source.
 
+For more information, see :ref:`contextual-markers` and :ref:`translator-comments`.
+
 Everything else
 ~~~~~~~~~~~~~~~