unicode: Filled in some missing pieces of documentation.

git-svn-id: http://code.djangoproject.com/svn/django/branches/unicode@5340 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/i18n.txt

@@ -296,6 +296,71 @@ string, so they don't need to be aware of translations.
 
 .. _Django templates: ../templates_python/
 
+Working with lazy translation objects
+=====================================
+
+Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models
+and utility functions is a common operation. When you are working with these
+objects elsewhere in your code, you should ensure that you don't accidentally
+convert them to strings, because they should be converted as late as possible
+(so that the correct locale is in effect). This necessitates the use of a
+couple of helper functions.
+
+Joining strings: string_concat()
+--------------------------------
+
+Standard Python string joins (``''.join([...])``) will not work on lists
+containing lazy translation objects. Instead, you can use
+``django.utils.translation.string_concat()``, which creates a lazy object that
+concatenates its contents *and* converts them to strings only when the result
+is included in a string. For example::
+
+    from django.utils.translation import string_concat
+    ...
+    name = ugettext_lazy(u'John Lennon')
+    instrument = ugettext_lazy(u'guitar')
+    result = string_concat([name, ': ', instrument])
+
+In this case, the lazy translations in ``result`` will only be converted to
+strings when ``result`` itself is used in a string (usually at template
+rendering time).
+
+The allow_lazy() decorator
+--------------------------
+
+There are a lot of useful utility functions in Django (particularly in
+``django.utils``) that take a string as their first argument and do something
+to that string. These functions are used by template filters as well as
+directly in other code.
+
+If you write your own similar functions, you will rapidly come across the
+problem of what to do when the first argument is a lazy translation object.
+You don't want to convert it to a string immediately, because you may be using
+this function outside of a view (and hence the current thread's locale setting
+will not be correct). For cases like this, the
+``django.utils.functional.allow_lazy()`` decorator will be useful. It modifies
+the function so that *if* it is called with a lazy translation as the first
+argument, the function evaluation is delayed until it needs to be converted to
+a string.
+
+For example::
+
+    from django.utils.functional import allow_lazy
+
+    def fancy_utility_function(s, ...):
+        # Do some conversion on string 's'
+        ...
+    fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
+
+The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
+a number of extra arguments specifying the type(s) that the original function
+can return. Usually, it will be enough to just include ``unicode`` here and
+ensure that your function returns Unicode strings.
+
+Using this decorator means you can write your function and assume that the
+input is a proper string, then add support for lazy translation objects at the
+end.
+
 How to create language files
 ============================
 

docs/unicode.txt

@@ -87,6 +87,11 @@ if you examine an object and it claims to be a
 Calling ``unicode()`` with the translation as the argument will generate a
 string in the current locale.
 
+For more details about lazy translation objects, refer to the
+internationalization_ documentation.
+
+.. _internationalization: ../i18n/#lazy-translation
+
 .. _utility functions:
 
 Useful utility functions
@@ -147,7 +152,8 @@ characters). Getting the quoting and conversion from IRI to URI correct can be
 a little tricky, so Django provides some assistance.
 
     * The function ``django.utils.encoding.iri_to_uri()`` implements the
-      conversion from IRI to URI as required by `the specification`_.
+      conversion from IRI to URI as required by the specification (`RFC
+      3987`_).
 
     * The functions ``django.utils.http.urlquote()`` and
       ``django.utils.http.urlquote_plus()`` are versions of Python's standard
@@ -187,9 +193,17 @@ you can construct your IRI without worrying about whether it contains
 non-ASCII characters and then, right at the end, call ``iri_to_uri()`` on the
 result.
 
+The ``iri_to_uri()`` function is also idempotent, which means the following is
+always true::
+
+    iri_to_uri(iri_to_uri(some_string)) = iri_to_uri(some_string)
+
+So you can safely call it multiple times on the same IRI without risking
+double-quoting problems.
+
 .. _URI: http://www.ietf.org/rfc/rfc2396.txt
 .. _IRI: http://www.ietf.org/rfc/rfc3987.txt
-.. _the specification: IRI_
+.. _RFC 3987: IRI_
 
 Models
 ======
@@ -246,7 +260,6 @@ something like "Jack visited Paris & Orléans". (In fact, the ``iri_to_uri()``
 call isn't strictly necessary in the above example, because all the
 non-ASCII characters would have been removed in quoting in the first line.)
 
-.. _RFC 3987: IRI_
 .. _above: uri_and_iri_
 
 The database API
@@ -275,6 +288,20 @@ it may be convenient to use an encoding other than UTF-8. You should set the
 ``DEFAULT_CHARSET`` parameter to control the rendered template encoding (the
 default setting is utf-8).
 
+Template tags and filters
+-------------------------
+
+A couple of tips to remember when writing your own template tags and filters:
+
+    * Always return Unicode strings from a template tag's ``render()`` method
+      and from template filters.
+
+    * Use ``force_unicode()`` in preference to ``smart_unicode()`` in these
+      places. Tag rendering and filter calls occur as the template is being
+      rendered, so there is no advantage to postponing the conversion of lazy
+      transation objects into strings any longer. It is easier to work solely
+      with Unicode strings at this point.
+
 E-mail
 ======