Code

Ticket #8768: ugettext_lazy-string-context.diff

File ugettext_lazy-string-context.diff, 2.0 KB (added by mrts, 6 years ago)
Line 
1Index: docs/topics/i18n.txt
2===================================================================
3--- docs/topics/i18n.txt        (revision 8846)
4+++ docs/topics/i18n.txt        (working copy)
5@@ -159,9 +159,9 @@
6 Lazy translation
7 ~~~~~~~~~~~~~~~~
8 
9-Use the function ``django.utils.translation.ugettext_lazy()`` to translate
10+Use the function :func:`django.utils.translation.ugettext_lazy` to translate
11 strings lazily -- when the value is accessed rather than when the
12-``ugettext_lazy()`` function is called.
13+:func:`~django.utils.translation.ugettext_lazy` function is called.
14 
15 For example, to translate a model's ``help_text``, do the following::
16 
17@@ -170,10 +170,26 @@
18     class MyThing(models.Model):
19         name = models.CharField(help_text=ugettext_lazy('This is the help text'))
20 
21-In this example, ``ugettext_lazy()`` stores a lazy reference to the string --
22-not the actual translation. The translation itself will be done when the string
23-is used in a string context, such as template rendering on the Django admin site.
24+In this example, :func:`~django.utils.translation.ugettext_lazy` stores a lazy
25+reference to the string, not the actual translation. The translation itself
26+will be done when the string is used in unicode context, such as template
27+rendering on the Django admin site -- but not in ordinary string context, e.g.
28+not with the string formatting operator ``%``. If you need to enforce
29+translation in your own code, use :func:`django.utils.encoding.force_unicode`.
30 
31+For example::
32+
33+    >>> from django.utils.encoding import force_unicode
34+    >>> from django.utils.translation import ugettext_lazy
35+
36+    # no translation in ordinary string context
37+    >>> str(ugettext_lazy("Hello there"))
38+    '<django.utils.functional.__proxy__ object at 0xf2b2d0>'
39+
40+    # translation performed in explicit unicode context
41+    >>> force_unicode(ugettext_lazy("Hello there"))
42+    u'Hello there'
43+
44 If you don't like the verbose name ``ugettext_lazy``, you can just alias it as
45 ``_`` (underscore), like so::
46