Changeset 5340

Timestamp:

05/25/07 04:16:34 (1 year ago)

Author:

mtredinnick

Message:

unicode: Filled in some missing pieces of documentation.

Files:

• django/branches/unicode/docs/i18n.txt (modified) (1 diff)
• django/branches/unicode/docs/unicode.txt (modified) (5 diffs)

django/branches/unicode/docs/i18n.txt

@@ -296 +296 @@
-
-.. _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

django/branches/unicode/docs/unicode.txt

@@ -88 +88 @@
-string in the current locale.
-
+For more details about lazy translation objects, refer to the
+internationalization_ documentation.
+
+.. _internationalization: ../i18n/#lazy-translation
+
-.. _utility functions:
-
@@ -148 +153 @@
-
-    * The function ``django.utils.encoding.iri_to_uri()`` implements the
-
+
+
-
-    * The functions ``django.utils.http.urlquote()`` and
@@ -188 +194 @@
-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
+RFC 3987
-
-Models
@@ -247 +261 @@
-non-ASCII characters would have been removed in quoting in the first line.)
-
-.. _RFC 3987: IRI_
-.. _above: uri_and_iri_
-
@@ -278 +291 @@
-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
-======