Django

Code

Changeset 1543

Show
Ignore:
Timestamp:
12/04/05 13:50:12 (3 years ago)
Author:
adrian
Message:

Lightly reworded docs/i18n.txt section on JavaScript?

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/i18n.txt

    r1540 r1543  
    553553=========================== 
    554554 
    555 Adding translations to JavaScript poses some new problems. The main problem 
    556 is, your JavaScript code doesn't have access to a readily available ``gettext`` 
    557 implementation. The second problem is, your JavaScript code doesn't have access 
    558 to .po or .mo files - they need to be delivered by the server. Additionally you 
    559 want to keep those translation catalogs as small as possible. Django provides 
    560 an integrated solution for all these problems. 
    561  
    562 The ``javascript_catalog`` view function 
    563 ---------------------------------------- 
    564  
    565 This is a generic view that will send out a JavaScript code library with functions 
    566 that mimick the ``gettext`` interface and an array with translation strings. Those 
    567 translation strings are taken from the application, project or django core, just 
    568 as you specifiy in either the info_dict or the URL. 
     555Adding translations to JavaScript poses some problems: 
     556 
     557    * JavaScript code doesn't have access to a ``gettext`` implementation. 
     558 
     559    * JavaScript code doesn't have access to .po or .mo files; they need to be 
     560      delivered by the server. 
     561 
     562    * The translation catalogs for JavaScript should be kept as small as 
     563      possible. 
     564 
     565Django provides an integrated solution for these problems: It passes the 
     566translations into JavaScript, so you can call ``gettext``, etc., from within 
     567JavaScript. 
     568 
     569The ``javascript_catalog`` view 
     570------------------------------- 
     571 
     572The main solution to these problems is the ``javascript_catalog`` view, which 
     573sends out a JavaScript code library with functions that mimick the ``gettext`` 
     574interface, plus an array of translation strings. Those translation strings are 
     575taken from the application, project or Django core, according to what you 
     576specify in either the {{{info_dict}}} or the URL. 
    569577 
    570578You hook it up like this:: 
    …… 
    578586    ) 
    579587 
    580 The package specifications are the same as with ``INSTALLED_APPS``. You can 
    581 specify multiple packages - in that case all those catalogs are merged into 
    582 one catalog. This is usefull if you have JavaScript that uses strings from different 
    583 applications. 
    584  
    585 Additionally you can make the view dynamic by putting the packages into the URL 
    586 specification:: 
     588Each string in ``packages`` should be in Python dotted-package syntax (the 
     589same format as the strings in ``INSTALLED_APPS``) and should refer to a package 
     590that contains a ``locale`` directory. If you specify multiple packages, all 
     591those catalogs aremerged into one catalog. This is useful if you have 
     592JavaScript that uses strings from different applications. 
     593 
     594You can make the view dynamic by putting the packages into the URL pattern:: 
    587595 
    588596    urlpatterns = patterns('', 
    …… 
    590598    ) 
    591599 
    592 This way you can specify the packages as a list of package names delimited by '+' 
    593 signs in the URL. This is especially useful if your pages use code from different 
    594 apps and this changes often and you don't want to pull in one big catalog file. 
    595 Packages are limited to either ``django.conf`` or any package from the ``INSTALLED_APPS`` 
    596 setting. 
     600With this, you specify the packages as a list of package names delimited by '+' 
     601signs in the URL. This is especially useful if your pages use code from 
     602different apps and this changes often and you don't want to pull in one big 
     603catalog file. As a security measure, these values can only be either 
     604``django.conf`` or any package from the ``INSTALLED_APPS`` setting. 
    597605 
    598606Using the JavaScript translation catalog 
    599607---------------------------------------- 
    600608 
    601 To make use of the catalog, you just have to pull in the dynamically generated 
    602 script like this:: 
    603  
    604     <script type="text/javascript" src="../../../jsi18n/"></script> 
     609To use the catalog, just pull in the dynamically generated script like this:: 
     610 
     611    <script type="text/javascript" src="/path/to/jsi18n/"></script> 
    605612 
    606613This is how the admin fetches the translation catalog from the server. When the 
    607 catalog is loaded, your JavaScript code can use the standard ``gettext`` interface 
    608 to access it:: 
     614catalog is loaded, your JavaScript code can use the standard ``gettext`` 
     615interface to access it:: 
    609616 
    610617    document.write(gettext('this is to be translated')); 
    …… 
    617624    s = interpolate(ngettext('this is %(count)s object', 'this are %(count)s objects', d.count), d); 
    618625 
    619 The ``interpolate`` function both supports positional interpolation and named interpolation. 
    620 So the above could have been written as:: 
     626The ``interpolate`` function supports both positional interpolation and named 
     627interpolation. So the above could have been written as:: 
    621628 
    622629    s = interpolate(ngettext('this is %s object', 'this are %s objects', 11), [11]); 
    623630 
    624 The interpolation syntax is borrowed from Python. You shouldn't go over the top with 
    625 string interpolation, though: this is still JavaScript, so the code will have to do 
    626 repeated regular expression substituions. This isn't as fast as string interpolation 
    627 in Python, so keep it to those cases where you really need it (for example in conjunction with 
    628 ngettext to produce proper pluralizations). 
     631The interpolation syntax is borrowed from Python. You shouldn't go over the top 
     632with string interpolation, though: this is still JavaScript, so the code will 
     633have to do repeated regular-expression substitutions. This isn't as fast as 
     634string interpolation  in Python, so keep it to those cases where you really 
     635need it (for example, in conjunction with ``ngettext`` to produce proper 
     636pluralizations). 
    629637 
    630638Creating JavaScript translation catalogs 
    631639---------------------------------------- 
    632640 
    633 You create and update the translation catalogs the same way as the other django 
    634 translation catalogs with the make-messages.py tool. Only difference is, you have 
    635 to provide a ``-d djangojs`` parameter like this:: 
     641You create and update the translation catalogs the same way as the other Django 
     642translation catalogs -- with the {{{make-messages.py}}} tool. The only 
     643difference is you need to provide a ``-d djangojs`` parameter, like this:: 
    636644 
    637645    make-messages.py -d djangojs -l de 
    …… 
    639647This would create or update the translation catalog for JavaScript for German. 
    640648After updating translation catalogs, just run ``compile-messages.py`` the same 
    641 way as you do with normal django translation catalogs. 
     649way as you do with normal Django translation catalogs. 
    642650 
    643651Specialities of Django translation