Django

Code

Show
Ignore:
Timestamp:
07/03/07 13:29:56 (2 years ago)
Author:
adrian
Message:

unicode: Made some documentation edits and inconsequential typo fixes throughout code

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/branches/unicode/docs/i18n.txt

    r5340 r5597  
    6969~~~~~~~~~~~~~~~~~~~~ 
    7070 
    71 Specify a translation string by using the function ``ugettext()``. Since you 
    72 may well be typing this a lot, it's often worthwhile importing it as a shorter 
    73 alias and ``_`` is a very common choice. 
     71Specify a translation string by using the function ``ugettext()``. It's 
     72convention to import this as a shorter alias, ``_``, to save typing. 
    7473 
    7574.. note:: 
    …… 
    7877    not to follow this practice, for a couple of reasons: 
    7978 
    80       1. For international character set (unicode) support, you really wanting 
    81          to be using ``ugettext()``, rather than ``gettext()``. Sometimes, you 
    82          should be using ``ugettext_lazy()`` as the default translation method 
    83          for a particular file. By not installing ``_`` directly, the 
    84          developer has to think about which is the most appropriate function 
    85          to use. 
    86  
    87       2. Python's interactive shell uses ``_`` to represent "the previous 
    88          result". This is also used in doctest tests and having ``_()`` causes 
    89          interference. Explicitly importing ``ugettext()`` as ``_()`` avoids 
    90          this problem. 
     79      1. For international character set (Unicode) support, ``ugettext()`` is 
     80         more useful than ``gettext()``. Sometimes, you should be using 
     81         ``ugettext_lazy()`` as the default translation method for a particular 
     82         file. Without ``_()`` in the global namespace, the developer has to 
     83         think about which is the most appropriate translation function. 
     84 
     85      2. The underscore character (``_``) is used to represent "the previous 
     86         result" in Python's interactive shell and doctest tests. Installing a 
     87         global ``_()`` function causes interference. Explicitly importing 
     88         ``ugettext()`` as ``_()`` avoids this problem. 
    9189 
    9290In this example, the text ``"Welcome to my site."`` is marked as a translation 
    …… 
    9997        return HttpResponse(output) 
    10098 
    101 Obviously you could code this without using the alias. This example is 
     99Obviously, you could code this without using the alias. This example is 
    102100identical to the previous one:: 
    103101 
    …… 
    301299 
    302300Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models 
    303 and utility functions is a common operation. When you are working with these 
     301and utility functions is a common operation. When you're working with these 
    304302objects elsewhere in your code, you should ensure that you don't accidentally 
    305303convert them to strings, because they should be converted as late as possible 
    …… 
    329327-------------------------- 
    330328 
    331 There are a lot of useful utility functions in Django (particularly in 
    332 ``django.utils``) that take a string as their first argument and do something 
    333 to that string. These functions are used by template filters as well as 
    334 directly in other code. 
    335  
    336 If you write your own similar functions, you will rapidly come across the 
    337 problem of what to do when the first argument is a lazy translation object. 
    338 You don't want to convert it to a string immediately, because you may be using 
    339 this function outside of a view (and hence the current thread's locale setting 
    340 will not be correct). For cases like this, the 
    341 ``django.utils.functional.allow_lazy()`` decorator will be useful. It modifies 
    342 the function so that *if* it is called with a lazy translation as the first 
    343 argument, the function evaluation is delayed until it needs to be converted to 
    344 a string. 
     329Django offers many utility functions (particularly in ``django.utils``) that 
     330take a string as their first argument and do something to that string. These 
     331functions are used by template filters as well as directly in other code. 
     332 
     333If you write your own similar functions and deal with translations, you'll  
     334face the problem of what to do when the first argument is a lazy translation 
     335object. You don't want to convert it to a string immediately, because you might 
     336be using this function outside of a view (and hence the current thread's locale 
     337setting will not be correct). 
     338 
     339For cases like this, use the  ``django.utils.functional.allow_lazy()`` 
     340decorator. It modifies the function so that *if* it's called with a lazy 
     341translation as the first argument, the function evaluation is delayed until it 
     342needs to be converted to a string. 
    345343 
    346344For example:: 
    …… 
    354352 
    355353The ``allow_lazy()`` decorator takes, in addition to the function to decorate, 
    356 a number of extra arguments specifying the type(s) that the original function 
    357 can return. Usually, it will be enough to just include ``unicode`` here and 
    358 ensure that your function returns Unicode strings. 
     354a number of extra arguments (``*args``) specifying the type(s) that the 
     355original function can return. Usually, it's enough to include ``unicode`` here 
     356and ensure that your function returns only Unicode strings. 
    359357 
    360358Using this decorator means you can write your function and assume that the