Document that ugettext_lazy returns `<django.utils.functional.__proxy__ object at 0x11b1310>` in non-unicode string context

[mrts]

Docs state that "... 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, ...".

However, ugettext_lazy("Foo") does not actually provide the translation in string context:

FOO = {
 'a' : ugettext_lazy("Foo"),
}

def bar():
 return "bar %s" % FOO['a']

does not return the translation for "Foo" but the string rep <django.utils.functional.__proxy__ object at 0x11b1310> of the proxy object instead.

 return u"bar %s" % force_unicode(FOO['a'])

behaves as expected and should be documented near ugettext_lazy.

[mrts]

I'd say this is a confusing omission in docs and it's easy to commit, so upping the milestone to 1.0 tentatively.

[Matthias Kestenholz]

The patch only mentions force_unicode(), but unicode() would be enough.

>>> unicode(ugettext_lazy(u'Some string'))
u'Some string'

[Malcolm Tredinnick]

Some clarification could be made in this area, but this proposed patch isn't correct. "String context" is used intentionally in the documentation and does not mean "bytestrings" (e.g. str()). People need to be thinking that strings are either bytestrings or unicode. Format markers do work with ugettext_lazy(), etc.

The whole issue being reported here is that using something that is a proxy for a unicode string in a bytestring context fails. It also doesn't work in Python to use unicode where a bytestring is expected, so this isn't particularly unusual behaviour (try substituting a unicode string using %s into a normal bytestring and it fails similarly but with a different error). We should clarify that ugettext_lazy is only to be used where a unicode string is valid. But the rest of the stuff isn't necessary, since it only draws attention to incorrect usage (all the examples are covered by not using unicode where a bytestring is needed) and makes the root problem look much bigger than it actually is.

[Malcolm Tredinnick]

Fixed in r9168.

[Malcolm Tredinnick]

(In [9174]) [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.

[sunrise]

This works ok for me.. but It probably needs feedback. djangoproject Air Jordan