From 1e594b257e74f60292ca421f9df11d5fd7804ea6 Mon Sep 17 00:00:00 2001 From: Daniel Lindsley Date: Tue, 14 Apr 2015 12:19:20 -0400 Subject: [PATCH] [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 8ca9bc5ec326c0b01634dac264a9ba6f0857483e from master --- docs/topics/i18n/translation.txt | 117 +++++++++++++++++++++++++++++-- 1 file changed, 110 insertions(+), 7 deletions(-) diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index 484b9f55c2..a97027ce20 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -976,21 +976,39 @@ To use the catalog, just pull in the dynamically generated script like this: 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 -------------------