From f4a57bedd8c833b3fb12e646a031639db0d9e423 Mon Sep 17 00:00:00 2001 From: Malcolm Tredinnick Date: Mon, 6 Oct 2008 08:48:17 +0000 Subject: [PATCH] [1.0.X] Fixed #8768 -- Clarified that ugettext_lazy() results are unicode proxies and can't be used as bytestrings. Still a number of markup changes to be made in this file (and in this changeset). That's intentional for now, since I'm going to rewrite the file later this week. Backport of r9168 from trunk. git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@9174 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/topics/i18n.txt | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/topics/i18n.txt b/docs/topics/i18n.txt index 3e8234b342..af2af86cd7 100644 --- a/docs/topics/i18n.txt +++ b/docs/topics/i18n.txt @@ -174,7 +174,26 @@ For example, to translate a model's ``help_text``, do the following:: 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. +is used in a string context, such as template rendering on the Django admin +site. + +The result of a ``ugettext_lazy()`` call can be used wherever you would use a +unicode string (an object with type ``unicode``) in Python. If you try to use +it where a bytestring (a ``str`` object) is expected, things will not work as +expected, since a ``ugettext_lazy()`` object doesn't know how to convert +itself to a bytestring. You can't use a unicode string inside a bytestring, +either, so this is consistent with normal Python behavior. For example:: + + # This is fine: putting a unicode proxy into a unicode string. + u"Hello %s" % ugettext_lazy("people") + + # This will not work, since you cannot insert a unicode object + # into a bytestring (nor can you insert our unicode proxy there) + "Hello %s" % ugettext_lazy("people") + +If you ever see output that looks like ``"hello +"``, you have tried to insert the result of +``ugettext_lazy()`` into a bytestring. That's a bug in your code. If you don't like the verbose name ``ugettext_lazy``, you can just alias it as ``_`` (underscore), like so::