From f33cc0163de71816393246c37fd2fd178271a876 Mon Sep 17 00:00:00 2001 From: Georg Bauer Date: Sun, 4 Dec 2005 13:08:37 +0000 Subject: [PATCH] updated the i18n documentation with regard to JavaScript translations git-svn-id: http://code.djangoproject.com/svn/django/trunk@1532 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/i18n.txt | 104 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 97 insertions(+), 7 deletions(-) diff --git a/docs/i18n.txt b/docs/i18n.txt index 2bf5535f0a1..6d6c9397762 100644 --- a/docs/i18n.txt +++ b/docs/i18n.txt @@ -549,20 +549,110 @@ The easiest way out is to store applications that are not part of the project connected to your explicit project and not strings that are distributed independently. +Translations and JavaScript +=========================== + +Adding translations to JavaScript poses some new problems. The main problem +is, your JavaScript code doesn't have access to a readily available ``gettext`` +implementation. The second problem is, your JavaScript code doesn't have access +to .po or .mo files - they need to be delivered by the server. Additionally you +want to keep those translation catalogs as small as possible. Django provides +an integrated solution for all these problems. + +The ``javascript_catalog`` view function +---------------------------------------- + +This is a generic view that will send out a JavaScript code library with functions +that mimick the ``gettext`` interface and an array with translation strings. Those +translation strings are taken from the application, project or django core, just +as you specifiy in either the info_dict or the URL. + +You hook it up like this:: + + js_info_dict = { + 'packages': ('your.app.package',), + } + + urlpatterns = patterns('', + (r'^jsi18n/$', 'django.views.i18n.javascript_catalog', js_info_dict), + ) + +The package specifications are the same as with ``INSTALLED_APPS``. You can +specify multiple packages - in that case all those catalogs are merged into +one catalog. This is usefull if you have JavaScript that uses strings from different +applications. + +Additionally you can make the view dynamic by putting the packages into the URL +specification:: + + urlpatterns = patterns('', + (r'^jsi18n/(?P\S+?)/$, 'django.views.i18n.javascript_catalog'), + ) + +This way you can specify the packages as a list of package names delimited by '+' +signs in the URL. This is especially useful if your pages use code from different +apps and this changes often and you don't want to pull in one big catalog file. +Packages are limited to either ``django.conf`` or any package from the ``INSTALLED_APPS`` +setting. + +Using the JavaScript translation catalog +---------------------------------------- + +To make use of the catalog, you just have to pull in the dynamically generated +script like this:: + + + +This is how the admin fetches the translation catalog from the server. When the +catalog is loaded, your JavaScript code can use the standard ``gettext`` interface +to access it:: + + document.write(gettext('this is to be translated')); + +There even is a ``ngettext`` interface and a string interpolation function:: + + d = { + count: 10 + }; + s = interpolate(ngettext('this is %(count)s object', 'this are %(count)s objects', d.count), d); + +The ``interpolate`` function both supports positional interpolation and named interpolation. +So the above could have been written as:: + + s = interpolate(ngettext('this is %s object', 'this are %s objects', 11), 11); + +The interpolation syntax is borrowed from Python. You shouldn't go over the top with +string interpolation, though: this is still JavaScript, so the code will have to do +repeated regular expression substituions. This isn't as fast as string interpolation +in Python, so keep it to those cases where you really need it (for example in conjunction with +ngettext to produce proper pluralizations). + +Creating JavaScript translation catalogs +---------------------------------------- + +You create and update the translation catalogs the same way as the other django +translation catalogs with the make-messages.py tool. Only difference is, you have +to provide a ``-d djangojs`` parameter like this:: + + make-messages.py -d djangojs -l de + +This would create or update the translation catalog for JavaScript for German. +After updating translation catalogs, just run ``compile-messages.py`` the same +way as you do with normal django translation catalogs. + Specialities of Django translation ================================== If you know ``gettext``, you might note these specialities in the way Django does translation: - * The string domain is always ``django``. The string domain is used to + * The string domain is ``django`` or ``djangojs``. The string domain is used to differentiate between different programs that store their data in a - common message-file library (usually ``/usr/share/locale/``). In Django's - case, there are Django-specific locale libraries, so the domain itself - isn't used. We could store app message files with different names and put - them, say, in the project library, but we decided against this. With - message files in the application tree, apps can be distributed more - easily. + common message-file library (usually ``/usr/share/locale/``). The ``django`` + domain is used for python and template translation strings and is loaded into + the global translation catalogs. The ``djangojs`` domain is only used for + JavaScript translation catalogs to make sure that those are as small as + possible. * Django only uses ``gettext`` and ``gettext_noop``. That's because Django always uses ``DEFAULT_CHARSET`` strings internally. There isn't much use in using ``ugettext``, because you'll always need to produce utf-8