Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
  • Loading branch information...
commit f33cc0163de71816393246c37fd2fd178271a876 1 parent eaed1a7
authored December 04, 2005

Showing 1 changed file with 97 additions and 7 deletions. Show diff stats Hide diff stats

  1. 104  docs/i18n.txt
104  docs/i18n.txt
@@ -549,20 +549,110 @@ The easiest way out is to store applications that are not part of the project
549 549
 connected to your explicit project and not strings that are distributed
550 550
 independently.
551 551
 
  552
+Translations and JavaScript
  553
+===========================
  554
+
  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.
  569
+
  570
+You hook it up like this::
  571
+
  572
+    js_info_dict = {
  573
+        'packages': ('your.app.package',),
  574
+    }
  575
+
  576
+    urlpatterns = patterns('',
  577
+        (r'^jsi18n/$', 'django.views.i18n.javascript_catalog', js_info_dict),
  578
+    )
  579
+
  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::
  587
+
  588
+    urlpatterns = patterns('',
  589
+        (r'^jsi18n/(?P<packages>\S+?)/$, 'django.views.i18n.javascript_catalog'),
  590
+    )
  591
+
  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.
  597
+
  598
+Using the JavaScript translation catalog
  599
+----------------------------------------
  600
+
  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>
  605
+
  606
+This 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::
  609
+
  610
+    document.write(gettext('this is to be translated'));
  611
+
  612
+There even is a ``ngettext`` interface and a string interpolation function::
  613
+
  614
+    d = {
  615
+        count: 10
  616
+    };
  617
+    s = interpolate(ngettext('this is %(count)s object', 'this are %(count)s objects', d.count), d);
  618
+
  619
+The ``interpolate`` function both supports positional interpolation and named interpolation.
  620
+So the above could have been written as::
  621
+
  622
+    s = interpolate(ngettext('this is %s object', 'this are %s objects', 11), 11);
  623
+
  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).
  629
+
  630
+Creating JavaScript translation catalogs
  631
+----------------------------------------
  632
+
  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::
  636
+
  637
+    make-messages.py -d djangojs -l de
  638
+
  639
+This would create or update the translation catalog for JavaScript for German.
  640
+After updating translation catalogs, just run ``compile-messages.py`` the same
  641
+way as you do with normal django translation catalogs.
  642
+
552 643
 Specialities of Django translation
553 644
 ==================================
554 645
 
555 646
 If you know ``gettext``, you might note these specialities in the way Django
556 647
 does translation:
557 648
 
558  
-    * The string domain is always ``django``. The string domain is used to
  649
+    * The string domain is ``django`` or ``djangojs``. The string domain is used to
559 650
       differentiate between different programs that store their data in a
560  
-      common message-file library (usually ``/usr/share/locale/``). In Django's
561  
-      case, there are Django-specific locale libraries, so the domain itself
562  
-      isn't used. We could store app message files with different names and put
563  
-      them, say, in the project library, but we decided against this. With
564  
-      message files in the application tree, apps can be distributed more
565  
-      easily.
  651
+      common message-file library (usually ``/usr/share/locale/``). The ``django``
  652
+      domain is used for python and template translation strings and is loaded into
  653
+      the global translation catalogs. The ``djangojs`` domain is only used for
  654
+      JavaScript translation catalogs to make sure that those are as small as
  655
+      possible.
566 656
     * Django only uses ``gettext`` and ``gettext_noop``. That's because Django
567 657
       always uses ``DEFAULT_CHARSET`` strings internally. There isn't much use
568 658
       in using ``ugettext``, because you'll always need to produce utf-8

0 notes on commit f33cc01

Please sign in to comment.
Something went wrong with that request. Please try again.