py_tasks_melange: comparison thirdparty/google_appengine/lib/django/docs/i18n.txt

equal deleted inserted replaced

-:261778de26ff
+:620f9b141567
+====================
+Internationalization
+====================
+Django has full support for internationalization of text in code and templates.
+Here's how it works.
+Overview
+========
+The goal of internationalization is to allow a single Web application to offer
+its content and functionality in multiple languages.
+You, the Django developer, can accomplish this goal by adding a minimal amount
+of hooks to your Python code and templates. These hooks are called
+**translation strings**. They tell Django: "This text should be translated into
+the end user's language, if a translation for this text is available in that
+language."
+Django takes care of using these hooks to translate Web apps, on the fly,
+according to users' language preferences.
+Essentially, Django does two things:
+* It lets developers and template authors specify which parts of their apps
+should be translatable.
+* It uses these hooks to translate Web apps for particular users according
+to their language preferences.
+How to internationalize your app: in three steps
+------------------------------------------------
+1. Embed translation strings in your Python code and templates.
+2. Get translations for those strings, in whichever languages you want to
+support.
+3. Activate the locale middleware in your Django settings.
+.. admonition:: Behind the scenes
+Django's translation machinery uses the standard ``gettext`` module that
+comes with Python.
+If you don't need internationalization
+======================================
+Django's internationalization hooks are on by default, and that means there's a
+bit of i18n-related overhead in certain places of the framework. If you don't
+use internationalization, you should take the two seconds to set
+``USE_I18N = False`` in your settings file. If ``USE_I18N`` is set to
+``False``, then Django will make some optimizations so as not to load the
+internationalization machinery. See the `documentation for USE_I18N`_.
+You'll probably also want to remove ``'django.core.context_processors.i18n'``
+from your ``TEMPLATE_CONTEXT_PROCESSORS`` setting.
+.. _documentation for USE_I18N: ../settings/#use-i18n
+How to specify translation strings
+==================================
+Translation strings specify "This text should be translated." These strings can
+appear in your Python code and templates. It's your responsibility to mark
+translatable strings; the system can only translate strings it knows about.
+In Python code
+--------------
+Standard translation
+~~~~~~~~~~~~~~~~~~~~
+Specify a translation string by using the function ``_()``. (Yes, the name of
+the function is the "underscore" character.) This function is available
+globally in any Python module; you don't have to import it.
+In this example, the text ``"Welcome to my site."`` is marked as a translation
+string::
+def my_view(request):
+output = _("Welcome to my site.")
+return HttpResponse(output)
+The function ``django.utils.translation.gettext()`` is identical to ``_()``.
+This example is identical to the previous one::
+from django.utils.translation import gettext
+def my_view(request):
+output = gettext("Welcome to my site.")
+return HttpResponse(output)
+Translation works on computed values. This example is identical to the previous
+two::
+def my_view(request):
+words = ['Welcome', 'to', 'my', 'site.']
+output = _(' '.join(words))
+return HttpResponse(output)
+Translation works on variables. Again, here's an identical example::
+def my_view(request):
+sentence = 'Welcome to my site.'
+output = _(sentence)
+return HttpResponse(output)
+(The caveat with using variables or computed values, as in the previous two
+examples, is that Django's translation-string-detecting utility,
+``make-messages.py``, won't be able to find these strings. More on
+``make-messages`` later.)
+The strings you pass to ``_()`` or ``gettext()`` can take placeholders,
+specified with Python's standard named-string interpolation syntax. Example::
+def my_view(request, n):
+output = _('%(name)s is my name.') % {'name': n}
+return HttpResponse(output)
+This technique lets language-specific translations reorder the placeholder
+text. For example, an English translation may be ``"Adrian is my name."``,
+while a Spanish translation may be ``"Me llamo Adrian."`` -- with the
+placeholder (the name) placed after the translated text instead of before it.
+For this reason, you should use named-string interpolation (e.g., ``%(name)s``)
+instead of positional interpolation (e.g., ``%s`` or ``%d``). If you used
+positional interpolation, translations wouldn't be able to reorder placeholder
+text.
+Marking strings as no-op
+~~~~~~~~~~~~~~~~~~~~~~~~
+Use the function ``django.utils.translation.gettext_noop()`` to mark a string
+as a translation string without translating it. The string is later translated
+from a variable.
+Use this if you have constant strings that should be stored in the source
+language because they are exchanged over systems or users -- such as strings in
+a database -- but should be translated at the last possible point in time, such
+as when the string is presented to the user.
+Lazy translation
+~~~~~~~~~~~~~~~~
+Use the function ``django.utils.translation.gettext_lazy()`` to translate
+strings lazily -- when the value is accessed rather than when the
+``gettext_lazy()`` function is called.
+For example, to translate a model's ``help_text``, do the following::
+from django.utils.translation import gettext_lazy
+class MyThing(models.Model):
+name = models.CharField(help_text=gettext_lazy('This is the help text'))
+In this example, ``gettext_lazy()`` stores a lazy reference to the string --
+not the actual translation. The translation itself will be done when the string
+is used in a string context, such as template rendering on the Django admin site.
+If you don't like the verbose name ``gettext_lazy``, you can just alias it as
+``_`` (underscore), like so::
+from django.utils.translation import gettext_lazy as _
+class MyThing(models.Model):
+name = models.CharField(help_text=_('This is the help text'))
+Always use lazy translations in `Django models`_. And it's a good idea to add
+translations for the field names and table names, too. This means writing
+explicit ``verbose_name`` and ``verbose_name_plural`` options in the ``Meta``
+class, though::
+from django.utils.translation import gettext_lazy as _
+class MyThing(models.Model):
+name = models.CharField(_('name'), help_text=_('This is the help text'))
+class Meta:
+verbose_name = _('my thing')
+verbose_name_plural = _('mythings')
+.. _Django models: ../model_api/
+Pluralization
+~~~~~~~~~~~~~
+Use the function ``django.utils.translation.ngettext()`` to specify pluralized
+messages. Example::
+from django.utils.translation import ngettext
+def hello_world(request, count):
+page = ngettext('there is %(count)d object', 'there are %(count)d objects', count) % {
+'count': count,
+}
+return HttpResponse(page)
+``ngettext`` takes three arguments: the singular translation string, the plural
+translation string and the number of objects (which is passed to the
+translation languages as the ``count`` variable).
+In template code
+----------------
+Using translations in `Django templates`_ uses two template tags and a slightly
+different syntax than in Python code. To give your template access to these
+tags, put ``{% load i18n %}`` toward the top of your template.
+The ``{% trans %}`` template tag translates a constant string or a variable
+content::
+<title>{% trans "This is the title." %}</title>
+If you only want to mark a value for translation, but translate it later from a
+variable, use the ``noop`` option::
+<title>{% trans "value" noop %}</title>
+It's not possible to use template variables in ``{% trans %}`` -- only constant
+strings, in single or double quotes, are allowed. If your translations require
+variables (placeholders), use ``{% blocktrans %}``. Example::
+{% blocktrans %}This will have {{ value }} inside.{% endblocktrans %}
+To translate a template expression -- say, using template filters -- you need
+to bind the expression to a local variable for use within the translation
+block::
+{% blocktrans with value|filter as myvar %}
+This will have {{ myvar }} inside.
+{% endblocktrans %}
+If you need to bind more than one expression inside a ``blocktrans`` tag,
+separate the pieces with ``and``::
+{% blocktrans with book|title as book_t and author|title as author_t %}
+This is {{ book_t }} by {{ author_t }}
+{% endblocktrans %}
+To pluralize, specify both the singular and plural forms with the
+``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and
+``{% endblocktrans %}``. Example::
+{% blocktrans count list|count as counter %}
+There is only one {{ name }} object.
+{% plural %}
+There are {{ counter }} {{ name }} objects.
+{% endblocktrans %}
+Internally, all block and inline translations use the appropriate
+``gettext`` / ``ngettext`` call.
+Each ``RequestContext`` has access to two translation-specific variables:
+* ``LANGUAGES`` is a list of tuples in which the first element is the
+language code and the second is the language name (in that language).
+* ``LANGUAGE_CODE`` is the current user's preferred language, as a string.
+Example: ``en-us``. (See "How language preference is discovered", below.)
+* ``LANGUAGE_BIDI`` is the current language's direction. If True, it's a
+right-to-left language, e.g: Hebrew, Arabic. If False it's a
+left-to-right language, e.g: English, French, German etc.
+If you don't use the ``RequestContext`` extension, you can get those values with
+three tags::
+{% get_current_language as LANGUAGE_CODE %}
+{% get_available_languages as LANGUAGES %}
+{% get_current_language_bidi as LANGUAGE_BIDI %}
+These tags also require a ``{% load i18n %}``.
+Translation hooks are also available within any template block tag that accepts
+constant strings. In those cases, just use ``_()`` syntax to specify a
+translation string. Example::
+{% some_special_tag _("Page not found") value|yesno:_("yes,no") %}
+In this case, both the tag and the filter will see the already-translated
+string, so they don't need to be aware of translations.
+.. _Django templates: ../templates_python/
+How to create language files
+============================
+Once you've tagged your strings for later translation, you need to write (or
+obtain) the language translations themselves. Here's how that works.
+.. admonition:: Locale restrictions
+Django does not support localizing your application into a locale for
+which Django itself has not been translated. In this case, it will ignore
+your translation files. If you were to try this and Django supported it,
+you would inevitably see a mixture of translated strings (from your
+application) and English strings (from Django itself). If you want to
+support a locale for your application that is not already part of
+Django, you'll need to make at least a minimal translation of the Django
+core.
+Message files
+-------------
+The first step is to create a **message file** for a new language. A message
+file is a plain-text file, representing a single language, that contains all
+available translation strings and how they should be represented in the given
+language. Message files have a ``.po`` file extension.
+Django comes with a tool, ``bin/make-messages.py``, that automates the creation
+and upkeep of these files.
+To create or update a message file, run this command::
+bin/make-messages.py -l de
+...where ``de`` is the language code for the message file you want to create.
+The language code, in this case, is in locale format. For example, it's
+``pt_BR`` for Brazilian and ``de_AT`` for Austrian German.
+The script should be run from one of three places:
+* The root ``django`` directory (not a Subversion checkout, but the one
+that is linked-to via ``$PYTHONPATH`` or is located somewhere on that
+path).
+* The root directory of your Django project.
+* The root directory of your Django app.
+The script runs over the entire Django source tree and pulls out all strings
+marked for translation. It creates (or updates) a message file in the directory
+``conf/locale``. In the ``de`` example, the file will be
+``conf/locale/de/LC_MESSAGES/django.po``.
+If run over your project source tree or your application source tree, it will
+do the same, but the location of the locale directory is ``locale/LANG/LC_MESSAGES``
+(note the missing ``conf`` prefix).
+.. admonition:: No gettext?
+If you don't have the ``gettext`` utilities installed, ``make-messages.py``
+will create empty files. If that's the case, either install the ``gettext``
+utilities or just copy the English message file
+(``conf/locale/en/LC_MESSAGES/django.po``) and use it as a starting point;
+it's just an empty translation file.
+The format of ``.po`` files is straightforward. Each ``.po`` file contains a
+small bit of metadata, such as the translation maintainer's contact
+information, but the bulk of the file is a list of **messages** -- simple
+mappings between translation strings and the actual translated text for the
+particular language.
+For example, if your Django app contained a translation string for the text
+``"Welcome to my site."``, like so::
+_("Welcome to my site.")
+...then ``make-messages.py`` will have created a ``.po`` file containing the
+following snippet -- a message::
+#: path/to/python/module.py:23
+msgid "Welcome to my site."
+msgstr ""
+A quick explanation:
+* ``msgid`` is the translation string, which appears in the source. Don't
+change it.
+* ``msgstr`` is where you put the language-specific translation. It starts
+out empty, so it's your responsibility to change it. Make sure you keep
+the quotes around your translation.
+* As a convenience, each message includes the filename and line number
+from which the translation string was gleaned.
+Long messages are a special case. There, the first string directly after the
+``msgstr`` (or ``msgid``) is an empty string. Then the content itself will be
+written over the next few lines as one string per line. Those strings are
+directly concatenated. Don't forget trailing spaces within the strings;
+otherwise, they'll be tacked together without whitespace!
+.. admonition:: Mind your charset
+When creating a ``.po`` file with your favorite text editor, first edit
+the charset line (search for ``"CHARSET"``) and set it to the charset
+you'll be using to edit the content. Generally, utf-8 should work for most
+languages, but ``gettext`` should handle any charset you throw at it.
+To reexamine all source code and templates for new translation strings and
+update all message files for **all** languages, run this::
+make-messages.py -a
+Compiling message files
+-----------------------
+After you create your message file -- and each time you make changes to it --
+you'll need to compile it into a more efficient form, for use by ``gettext``.
+Do this with the ``bin/compile-messages.py`` utility.
+This tool runs over all available ``.po`` files and creates ``.mo`` files,
+which are binary files optimized for use by ``gettext``. In the same directory
+from which you ran ``make-messages.py``, run ``compile-messages.py`` like
+this::
+bin/compile-messages.py
+That's it. Your translations are ready for use.
+.. admonition:: A note to translators
+If you've created a translation in a language Django doesn't yet support,
+please let us know! See `Submitting and maintaining translations`_ for
+the steps to take.
+.. _Submitting and maintaining translations: ../contributing/
+How Django discovers language preference
+========================================
+Once you've prepared your translations -- or, if you just want to use the
+translations that come with Django -- you'll just need to activate translation
+for your app.
+Behind the scenes, Django has a very flexible model of deciding which language
+should be used -- installation-wide, for a particular user, or both.
+To set an installation-wide language preference, set ``LANGUAGE_CODE`` in your
+`settings file`_. Django uses this language as the default translation -- the
+final attempt if no other translator finds a translation.
+If all you want to do is run Django with your native language, and a language
+file is available for your language, all you need to do is set
+``LANGUAGE_CODE``.
+If you want to let each individual user specify which language he or she
+prefers, use ``LocaleMiddleware``. ``LocaleMiddleware`` enables language
+selection based on data from the request. It customizes content for each user.
+To use ``LocaleMiddleware``, add ``'django.middleware.locale.LocaleMiddleware'``
+to your ``MIDDLEWARE_CLASSES`` setting. Because middleware order matters, you
+should follow these guidelines:
+* Make sure it's one of the first middlewares installed.
+* It should come after ``SessionMiddleware``, because ``LocaleMiddleware``
+makes use of session data.
+* If you use ``CacheMiddleware``, put ``LocaleMiddleware`` after it.
+For example, your ``MIDDLEWARE_CLASSES`` might look like this::
+MIDDLEWARE_CLASSES = (
+'django.contrib.sessions.middleware.SessionMiddleware',
+'django.middleware.locale.LocaleMiddleware',
+'django.middleware.common.CommonMiddleware',
+)
+(For more on middleware, see the `middleware documentation`_.)
+``LocaleMiddleware`` tries to determine the user's language preference by
+following this algorithm:
+* First, it looks for a ``django_language`` key in the the current user's
+`session`_.
+* Failing that, it looks for a cookie called ``django_language``.
+* Failing that, it looks at the ``Accept-Language`` HTTP header. This
+header is sent by your browser and tells the server which language(s) you
+prefer, in order by priority. Django tries each language in the header
+until it finds one with available translations.
+* Failing that, it uses the global ``LANGUAGE_CODE`` setting.
+Notes:
+* In each of these places, the language preference is expected to be in the
+standard language format, as a string. For example, Brazilian is
+``pt-br``.
+* If a base language is available but the sublanguage specified is not,
+Django uses the base language. For example, if a user specifies ``de-at``
+(Austrian German) but Django only has ``de`` available, Django uses
+``de``.
+* Only languages listed in the `LANGUAGES setting`_ can be selected. If
+you want to restrict the language selection to a subset of provided
+languages (because your application doesn't provide all those languages),
+set ``LANGUAGES`` to a list of languages. For example::
+LANGUAGES = (
+('de', _('German')),
+('en', _('English')),
+)
+This example restricts languages that are available for automatic
+selection to German and English (and any sublanguage, like de-ch or
+en-us).
+.. _LANGUAGES setting: ../settings/#languages
+* If you define a custom ``LANGUAGES`` setting, as explained in the
+previous bullet, it's OK to mark the languages as translation strings
+-- but use a "dummy" ``gettext()`` function, not the one in
+``django.utils.translation``. You should *never* import
+``django.utils.translation`` from within your settings file, because that
+module in itself depends on the settings, and that would cause a circular
+import.
+The solution is to use a "dummy" ``gettext()`` function. Here's a sample
+settings file::
+gettext = lambda s: s
+LANGUAGES = (
+('de', gettext('German')),
+('en', gettext('English')),
+)
+With this arrangement, ``make-messages.py`` will still find and mark
+these strings for translation, but the translation won't happen at
+runtime -- so you'll have to remember to wrap the languages in the *real*
+``gettext()`` in any code that uses ``LANGUAGES`` at runtime.
+* The ``LocaleMiddleware`` can only select languages for which there is a
+Django-provided base translation. If you want to provide translations
+for your application that aren't already in the set of translations
+in Django's source tree, you'll want to provide at least basic
+translations for that language. For example, Django uses technical
+message IDs to translate date formats and time formats -- so you will
+need at least those translations for the system to work correctly.
+A good starting point is to copy the English ``.po`` file and to
+translate at least the technical messages -- maybe the validator
+messages, too.
+Technical message IDs are easily recognized; they're all upper case. You
+don't translate the message ID as with other messages, you provide the
+correct local variant on the provided English value. For example, with
+``DATETIME_FORMAT`` (or ``DATE_FORMAT`` or ``TIME_FORMAT``), this would
+be the format string that you want to use in your language. The format
+is identical to the format strings used by the ``now`` template tag.
+Once ``LocaleMiddleware`` determines the user's preference, it makes this
+preference available as ``request.LANGUAGE_CODE`` for each `request object`_.
+Feel free to read this value in your view code. Here's a simple example::
+def hello_world(request, count):
+if request.LANGUAGE_CODE == 'de-at':
+return HttpResponse("You prefer to read Austrian German.")
+else:
+return HttpResponse("You prefer to read another language.")
+Note that, with static (middleware-less) translation, the language is in
+``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's
+in ``request.LANGUAGE_CODE``.
+.. _settings file: ../settings/
+.. _middleware documentation: ../middleware/
+.. _session: ../sessions/
+.. _request object: ../request_response/#httprequest-objects
+The ``set_language`` redirect view
+==================================
+As a convenience, Django comes with a view, ``django.views.i18n.set_language``,
+that sets a user's language preference and redirects back to the previous page.
+Activate this view by adding the following line to your URLconf::
+(r'^i18n/', include('django.conf.urls.i18n')),
+(Note that this example makes the view available at ``/i18n/setlang/``.)
+The view expects to be called via the ``GET`` method, with a ``language``
+parameter set in the query string. If session support is enabled, the view
+saves the language choice in the user's session. Otherwise, it saves the
+language choice in a ``django_language`` cookie.
+After setting the language choice, Django redirects the user, following this
+algorithm:
+* Django looks for a ``next`` parameter in the query string.
+* If that doesn't exist, or is empty, Django tries the URL in the
+``Referer`` header.
+* If that's empty -- say, if a user's browser suppresses that header --
+then the user will be redirected to ``/`` (the site root) as a fallback.
+Here's example HTML template code::
+<form action="/i18n/setlang/" method="get">
+<input name="next" type="hidden" value="/next/page/" />
+<select name="language">
+{% for lang in LANGUAGES %}
+<option value="{{ lang.0 }}">{{ lang.1 }}</option>
+{% endfor %}
+</select>
+<input type="submit" value="Go" />
+</form>
+Using translations in your own projects
+=======================================
+Django looks for translations by following this algorithm:
+* First, it looks for a ``locale`` directory in the application directory
+of the view that's being called. If it finds a translation for the
+selected language, the translation will be installed.
+* Next, it looks for a ``locale`` directory in the project directory. If it
+finds a translation, the translation will be installed.
+* Finally, it checks the base translation in ``django/conf/locale``.
+This way, you can write applications that include their own translations, and
+you can override base translations in your project path. Or, you can just build
+a big project out of several apps and put all translations into one big project
+message file. The choice is yours.
+.. note::
+If you're using manually configured settings, as described in the
+`settings documentation`_, the ``locale`` directory in the project
+directory will not be examined, since Django loses the ability to work out
+the location of the project directory. (Django normally uses the location
+of the settings file to determine this, and a settings file doesn't exist
+if you're manually configuring your settings.)
+.. _settings documentation: ../settings/#using-settings-without-the-django-settings-module-environment-variable
+All message file repositories are structured the same way. They are:
+* ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
+* ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
+* All paths listed in ``LOCALE_PATHS`` in your settings file are
+searched in that order for ``<language>/LC_MESSAGES/django.(po|mo)``
+* ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
+To create message files, you use the same ``make-messages.py`` tool as with the
+Django message files. You only need to be in the right place -- in the directory
+where either the ``conf/locale`` (in case of the source tree) or the ``locale/``
+(in case of app messages or project messages) directory are located. And you
+use the same ``compile-messages.py`` to produce the binary ``django.mo`` files that
+are used by ``gettext``.
+Application message files are a bit complicated to discover -- they need the
+``LocaleMiddleware``. If you don't use the middleware, only the Django message
+files and project message files will be processed.
+Finally, you should give some thought to the structure of your translation
+files. If your applications need to be delivered to other users and will
+be used in other projects, you might want to use app-specific translations.
+But using app-specific translations and project translations could produce
+weird problems with ``make-messages``: ``make-messages`` will traverse all
+directories below the current path and so might put message IDs into the
+project message file that are already in application message files.
+The easiest way out is to store applications that are not part of the project
+(and so carry their own translations) outside the project tree. That way,
+``make-messages`` on the project level will only translate strings that are
+connected to your explicit project and not strings that are distributed
+independently.
+Translations and JavaScript
+===========================
+Adding translations to JavaScript poses some problems:
+* JavaScript code doesn't have access to a ``gettext`` implementation.
+* JavaScript code doesn't have access to .po or .mo files; they need to be
+delivered by the server.
+* The translation catalogs for JavaScript should be kept as small as
+possible.
+Django provides an integrated solution for these problems: It passes the
+translations into JavaScript, so you can call ``gettext``, etc., from within
+JavaScript.
+The ``javascript_catalog`` view
+-------------------------------
+The main solution to these problems is the ``javascript_catalog`` view, which
+sends out a JavaScript code library with functions that mimic the ``gettext``
+interface, plus an array of translation strings. Those translation strings are
+taken from the application, project or Django core, according to what you
+specify 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),
+)
+Each string in ``packages`` should be in Python dotted-package syntax (the
+same format as the strings in ``INSTALLED_APPS``) and should refer to a package
+that contains a ``locale`` directory. If you specify multiple packages, all
+those catalogs are merged into one catalog. This is useful if you have
+JavaScript that uses strings from different applications.
+You can make the view dynamic by putting the packages into the URL pattern::
+urlpatterns = patterns('',
+(r'^jsi18n/(?P<packages>\S+?)/$, 'django.views.i18n.javascript_catalog'),
+)
+With this, you 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. As a security measure, these values can only be either
+``django.conf`` or any package from the ``INSTALLED_APPS`` setting.
+Using the JavaScript translation catalog
+----------------------------------------
+To use the catalog, just pull in the dynamically generated script like this::
+<script type="text/javascript" src="/path/to/jsi18n/"></script>
+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 supports both 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 substitutions. 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. The only
+difference is you need 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 ``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/``). 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
+anyway.
+* Django doesn't use ``xgettext`` alone. It uses Python wrappers around
+``xgettext`` and ``msgfmt``. That's mostly for convenience.