diff options
author | Malcolm Tredinnick <malcolm.tredinnick@gmail.com> | 2007-05-25 09:16:34 +0000 |
---|---|---|
committer | Malcolm Tredinnick <malcolm.tredinnick@gmail.com> | 2007-05-25 09:16:34 +0000 |
commit | c98f0b14c42b3d49772f3ddf3c5974da79d8ad0e (patch) | |
tree | f01ef5547bcacf878732ce18fd15227e90a298ae | |
parent | 545173ed4ed8a34b83cfbe852bdbd6da5ba27ce0 (diff) | |
download | django-c98f0b14c42b3d49772f3ddf3c5974da79d8ad0e.tar.gz |
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
-rw-r--r-- | docs/i18n.txt | 65 | ||||
-rw-r--r-- | docs/unicode.txt | 33 |
2 files changed, 95 insertions, 3 deletions
diff --git a/docs/i18n.txt b/docs/i18n.txt index d8edaef615..80f98e20e4 100644 --- a/docs/i18n.txt +++ b/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 ============================ diff --git a/docs/unicode.txt b/docs/unicode.txt index 92b73ec240..41df214387 100644 --- a/docs/unicode.txt +++ b/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 ====== |