[1.10.x] Fixed #27221 -- Doc'd how to escape a percent symbol in ugettext().

Backport of b1a9041535db5d03dab7f205669f0ab7a47de854 from master

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 6a398dbcdd..1aa85e937d 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -1821,6 +1821,31 @@ That's it. Your translations are ready for use.
    (Byte Order Mark) so if your text editor adds such marks to the beginning of
    files by default then you will need to reconfigure it.
 
+Troubleshooting: ``ugettext()`` incorrectly detects ``python-format`` in strings with percent signs
+---------------------------------------------------------------------------------------------------
+
+In some cases, such as strings with a percent sign followed by a space and a
+:ref:`string conversion type <old-string-formatting>` (e.g.
+``_("10% interest")``), :func:`~django.utils.translation.ugettext` incorrectly
+flags strings with ``python-format``.
+
+If you try to compile message files with incorrectly flagged strings, you'll
+get an error message like ``number of format specifications in 'msgid' and
+'msgstr' does not match`` or ``'msgstr' is not a valid Python format string,
+unlike 'msgid'``.
+
+To workaround this, you can escape percent signs by adding a second percent
+sign::
+
+    from django.utils.translation import ugettext as _
+    output = _("10%% interest)
+
+Or you can use ``no-python-format`` so that all percent signs are treated as
+literals::
+
+    # xgettext:no-python-format
+    output = _("10% interest)
+
 .. _creating-message-files-from-js-code:
 
 Creating message files from JavaScript source code