[1.8.x] Fixed #23984 -- Added Javascript i18n documentation

This fleshes out the documentation around all of the exported
Javascript functions available from the ``javascript_catalog``
view.

Backport of 8ca9bc5ec3 from master
This commit is contained in:
Daniel Lindsley 2015-04-14 12:19:20 -04:00 committed by Tim Graham
parent 5678e4b93a
commit 1e594b257e
1 changed files with 110 additions and 7 deletions

View File

@ -976,21 +976,39 @@ To use the catalog, just pull in the dynamically generated script like this:
<script type="text/javascript" src="{% url 'django.views.i18n.javascript_catalog' %}"></script>
This uses reverse URL lookup to find the URL of the JavaScript catalog view.
When the catalog is loaded, your JavaScript code can use the standard
``gettext`` interface to access it::
When the catalog is loaded, your JavaScript code can use the following methods:
* ``gettext``
* ``ngettext``
* ``interpolate``
* ``get_format``
* ``gettext_noop``
* ``pgettext``
* ``npgettext``
* ``pluralidx``
``gettext``
~~~~~~~~~~~
The ``gettext`` function behaves similarly to the standard ``gettext``
interface within your Python code::
document.write(gettext('this is to be translated'));
There is also an ``ngettext`` interface::
``ngettext``
~~~~~~~~~~~~
The ``ngettext`` function provides an interface to pluralize words and
phrases::
var object_cnt = 1 // or 0, or 2, or 3, ...
s = ngettext('literal for the singular case',
'literal for the plural case', object_cnt);
and even a string interpolation function::
function interpolate(fmt, obj, named);
``interpolate``
~~~~~~~~~~~~~~~
The ``interpolate`` function supports dynamically populating a format string.
The interpolation syntax is borrowed from Python, so the ``interpolate``
function supports both positional and named interpolation:
@ -1005,7 +1023,7 @@ function supports both positional and named interpolation:
// s is 'There are 11 objects. Remaining: 20'
* Named interpolation: This mode is selected by passing the optional
boolean ``named`` parameter as true. ``obj`` contains a JavaScript
boolean ``named`` parameter as ``true``. ``obj`` contains a JavaScript
object or associative array. For example::
d = {
@ -1023,6 +1041,91 @@ 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).
``get_format``
~~~~~~~~~~~~~~
The ``get_format`` function has access to the configured i18n formatting
settings and can retrieve the format string for a given setting name::
document.write(get_format('DATE_FORMAT'));
// 'N j, Y'
It has access to the following settings:
* :setting:`DATE_FORMAT`
* :setting:`DATE_INPUT_FORMATS`
* :setting:`DATETIME_FORMAT`
* :setting:`DATETIME_INPUT_FORMATS`
* :setting:`DECIMAL_SEPARATOR`
* :setting:`FIRST_DAY_OF_WEEK`
* :setting:`MONTH_DAY_FORMAT`
* :setting:`NUMBER_GROUPING`
* :setting:`SHORT_DATE_FORMAT`
* :setting:`SHORT_DATETIME_FORMAT`
* :setting:`THOUSAND_SEPARATOR`
* :setting:`TIME_FORMAT`
* :setting:`TIME_INPUT_FORMATS`
* :setting:`YEAR_MONTH_FORMAT`
This is useful for maintaining formatting consistency with the Python-rendered
values.
``gettext_noop``
~~~~~~~~~~~~~~~~
This emulates the ``gettext`` function but does nothing, returning whatever
is passed to it::
document.write(gettext_noop('this will not be translated'));
This is useful for stubbing out portions of the code that will need translation
in the future.
``pgettext``
~~~~~~~~~~~~
The ``pgettext`` function behaves like the Python variant
(:func:`~django.utils.translation.pgettext()`), providing a contextually
translated word::
document.write(pgettext('month name', 'May'));
``npgettext``
~~~~~~~~~~~~~
The ``npgettext`` function also behaves like the Python variant
(:func:`~django.utils.translation.npgettext()`), providing a **pluralized**
contextually translated word::
document.write(npgettext('group', 'party', 1));
// party
document.write(npgettext('group', 'party', 2));
// parties
``pluralidx``
~~~~~~~~~~~~~
The ``pluralidx`` function works in a similar way to the :tfilter:`pluralize`
template filter, determining if a given ``count`` should use a plural form of
a word or not::
document.write(pluralidx(0));
// true
document.write(pluralidx(1));
// false
document.write(pluralidx(2));
// true
In the simplest case, if no custom pluralization is needed, this returns
``false`` for the integer ``1`` and ``true`` for all other numbers.
However, pluralization is not this simple in all languages. If the language does
not support pluralization, an empty value is provided.
Additionally, if there are complex rules around pluralization, the catalog view
will render a conditional expression. This will evaluate to either a ``true``
(should pluralize) or ``false`` (should **not** pluralize) value.
Note on performance
-------------------