Ticket #8768: ugettext_lazy-string-context.diff

docs/topics/i18n.txt

@@ -159 +159 @@
 Lazy translation
 ~~~~~~~~~~~~~~~~
 
-Use the function ``django.utils.translation.ugettext_lazy()`` to translate
+Use the function :func:`django.utils.translation.ugettext_lazy` to translate
 strings lazily -- when the value is accessed rather than when the
-``ugettext_lazy()`` function is called.
+:func:`~django.utils.translation.ugettext_lazy` function is called.
 
 For example, to translate a model's ``help_text``, do the following::
 
@@ -170 +170 @@
     class MyThing(models.Model):
         name = models.CharField(help_text=ugettext_lazy('This is the help text'))
 
-In this example, ``ugettext_lazy()`` stores a lazy reference to the string --
-not the actual translation. The translation itself will be done when the string
-is used in a string context, such as template rendering on the Django admin site.
+In this example, :func:`~django.utils.translation.ugettext_lazy` stores a lazy
+reference to the string, not the actual translation. The translation itself
+will be done when the string is used in unicode context, such as template
+rendering on the Django admin site -- but not in ordinary string context, e.g.
+not with the string formatting operator ``%``. If you need to enforce
+translation in your own code, use :func:`django.utils.encoding.force_unicode`.
 
+For example::
+
+    >>> from django.utils.encoding import force_unicode
+    >>> from django.utils.translation import ugettext_lazy
+
+    # no translation in ordinary string context
+    >>> str(ugettext_lazy("Hello there"))
+    '<django.utils.functional.__proxy__ object at 0xf2b2d0>'
+
+    # translation performed in explicit unicode context
+    >>> force_unicode(ugettext_lazy("Hello there"))
+    u'Hello there'
+
 If you don't like the verbose name ``ugettext_lazy``, you can just alias it as
 ``_`` (underscore), like so::