Fixed #19567 -- Added JavaScriptCatalog and JSONCatalog class-based views

Thanks Cristiano Coelho and Tim Graham for the reviews.

django/contrib/admin/sites.py

@@ -14,6 +14,7 @@ from django.utils.text import capfirst
 from django.utils.translation import ugettext as _, ugettext_lazy
 from django.views.decorators.cache import never_cache
 from django.views.decorators.csrf import csrf_protect
+from django.views.i18n import JavaScriptCatalog
 
 system_check_errors = []
 
@@ -316,15 +317,8 @@ class AdminSite(object):
     def i18n_javascript(self, request):
         """
         Displays the i18n JavaScript that the Django admin requires.
-
-        This takes into account the USE_I18N setting. If it's set to False, the
-        generated JavaScript will be leaner and faster.
         """
-        if settings.USE_I18N:
-            from django.views.i18n import javascript_catalog
-        else:
-            from django.views.i18n import null_javascript_catalog as javascript_catalog
-        return javascript_catalog(request, packages=['django.conf', 'django.contrib.admin'])
+        return JavaScriptCatalog.as_view(packages=['django.contrib.admin'])(request)
 
     @never_cache
     def logout(self, request, extra_context=None):

django/views/i18n.py

@@ -2,6 +2,7 @@ import importlib
 import itertools
 import json
 import os
+import warnings
 
 from django import http
 from django.apps import apps
@@ -10,6 +11,7 @@ from django.template import Context, Engine
 from django.urls import translate_url
 from django.utils import six
 from django.utils._os import upath
+from django.utils.deprecation import RemovedInDjango20Warning
 from django.utils.encoding import smart_text
 from django.utils.formats import get_format, get_format_modules
 from django.utils.http import is_safe_url, urlunquote
@@ -17,6 +19,7 @@ from django.utils.translation import (
     LANGUAGE_SESSION_KEY, check_for_language, get_language, to_locale,
 )
 from django.utils.translation.trans_real import DjangoTranslation
+from django.views.generic import View
 
 DEFAULT_PACKAGES = ['django.conf']
 LANGUAGE_QUERY_PARAMETER = 'language'
@@ -291,6 +294,10 @@ def javascript_catalog(request, domain='djangojs', packages=None):
     go to the djangojs domain. But this might be needed if you
     deliver your JavaScript source from Django templates.
     """
+    warnings.warn(
+        "The javascript_catalog() view is deprecated in favor of the "
+        "JavaScriptCatalog view.", RemovedInDjango20Warning, stacklevel=2
+    )
     locale = _get_locale(request)
     packages = _parse_packages(packages)
     catalog, plural = get_javascript_catalog(locale, domain, packages)
@@ -314,6 +321,10 @@ def json_catalog(request, domain='djangojs', packages=None):
             "plural": '...'  # Expression for plural forms, or null.
         }
     """
+    warnings.warn(
+        "The json_catalog() view is deprecated in favor of the "
+        "JSONCatalog view.", RemovedInDjango20Warning, stacklevel=2
+    )
     locale = _get_locale(request)
     packages = _parse_packages(packages)
     catalog, plural = get_javascript_catalog(locale, domain, packages)
@@ -323,3 +334,111 @@ def json_catalog(request, domain='djangojs', packages=None):
         'plural': plural,
     }
     return http.JsonResponse(data)
+
+
+class JavaScriptCatalog(View):
+    """
+    Return the selected language catalog as a JavaScript library.
+
+    Receives the list of packages to check for translations in the `packages`
+    kwarg either from the extra dictionary passed to the url() function or as a
+    plus-sign delimited string from the request. Default is 'django.conf'.
+
+    You can override the gettext domain for this view, but usually you don't
+    want to do that as JavaScript messages go to the djangojs domain. This
+    might be needed if you deliver your JavaScript source from Django templates.
+    """
+    domain = 'djangojs'
+    packages = None
+
+    def get(self, request, *args, **kwargs):
+        locale = get_language()
+        domain = kwargs.get('domain', self.domain)
+        # If packages are not provided, default to all installed packages, as
+        # DjangoTranslation without localedirs harvests them all.
+        packages = kwargs.get('packages', '').split('+') or self.packages
+        paths = self.get_paths(packages) if packages else None
+        self.translation = DjangoTranslation(locale, domain=domain, localedirs=paths)
+        context = self.get_context_data(**kwargs)
+        return self.render_to_response(context)
+
+    def get_paths(self, packages):
+        allowable_packages = dict((app_config.name, app_config) for app_config in apps.get_app_configs())
+        app_configs = [allowable_packages[p] for p in packages if p in allowable_packages]
+        # paths of requested packages
+        return [os.path.join(app.path, 'locale') for app in app_configs]
+
+    def get_plural(self):
+        plural = None
+        if '' in self.translation._catalog:
+            for line in self.translation._catalog[''].split('\n'):
+                if line.startswith('Plural-Forms:'):
+                    plural = line.split(':', 1)[1].strip()
+        if plural is not None:
+            # This should be a compiled function of a typical plural-form:
+            # Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 :
+            #               n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
+            plural = [el.strip() for el in plural.split(';') if el.strip().startswith('plural=')][0].split('=', 1)[1]
+        return plural
+
+    def get_catalog(self):
+        pdict = {}
+        maxcnts = {}
+        catalog = {}
+        trans_cat = self.translation._catalog
+        trans_fallback_cat = self.translation._fallback._catalog if self.translation._fallback else {}
+        for key, value in itertools.chain(six.iteritems(trans_cat), six.iteritems(trans_fallback_cat)):
+            if key == '' or key in catalog:
+                continue
+            if isinstance(key, six.string_types):
+                catalog[key] = value
+            elif isinstance(key, tuple):
+                msgid = key[0]
+                cnt = key[1]
+                maxcnts[msgid] = max(cnt, maxcnts.get(msgid, 0))
+                pdict.setdefault(msgid, {})[cnt] = value
+            else:
+                raise TypeError(key)
+        for k, v in pdict.items():
+            catalog[k] = [v.get(i, '') for i in range(maxcnts[msgid] + 1)]
+        return catalog
+
+    def get_context_data(self, **kwargs):
+        return {
+            'catalog': self.get_catalog(),
+            'formats': get_formats(),
+            'plural': self.get_plural(),
+        }
+
+    def render_to_response(self, context, **response_kwargs):
+        def indent(s):
+            return s.replace('\n', '\n  ')
+
+        template = Engine().from_string(js_catalog_template)
+        context['catalog_str'] = indent(
+            json.dumps(context['catalog'], sort_keys=True, indent=2)
+        ) if context['catalog'] else None
+        context['formats_str'] = indent(json.dumps(context['formats'], sort_keys=True, indent=2))
+
+        return http.HttpResponse(template.render(Context(context)), 'text/javascript')
+
+
+class JSONCatalog(JavaScriptCatalog):
+    """
+    Return the selected language catalog as a JSON object.
+
+    Receives the same parameters as JavaScriptCatalog and returns a response
+    with a JSON object of the following format:
+
+        {
+            "catalog": {
+                # Translations catalog
+            },
+            "formats": {
+                # Language formats for date, time, etc.
+            },
+            "plural": '...'  # Expression for plural forms, or null.
+        }
+    """
+    def render_to_response(self, context, **response_kwargs):
+        return http.JsonResponse(context)

docs/internals/deprecation.txt

@@ -156,6 +156,8 @@ details on these changes.
   ``Field.contribute_to_class()`` and ``virtual`` in
   ``Model._meta.add_field()`` will be removed.
 
+* The ``javascript_catalog()`` and ``json_catalog()`` views will be removed.
+
 .. _deprecation-removed-in-1.10:
 
 1.10

docs/releases/1.10.txt

@@ -277,6 +277,14 @@ Internationalization
   Content) for AJAX requests when there is no ``next`` parameter in ``POST`` or
   ``GET``.
 
+* The :class:`~django.views.i18n.JavaScriptCatalog` and
+  :class:`~django.views.i18n.JSONCatalog` class-based views supersede the
+  deprecated ``javascript_catalog()`` and ``json_catalog()`` function-based
+  views. The new views are almost equivalent to the old ones except that by
+  default the new views collect all JavaScript strings in the ``djangojs``
+  translation domain from all installed apps rather than only the JavaScript
+  strings from :setting:`LOCALE_PATHS`.
+
 Management Commands
 ~~~~~~~~~~~~~~~~~~~
 
@@ -929,6 +937,10 @@ Miscellaneous
   ``Model._meta.add_field()`` are deprecated in favor of ``private_only``
   and ``private``, respectively.
 
+* The ``javascript_catalog()`` and ``json_catalog()`` views are deprecated in
+  favor of class-based views :class:`~django.views.i18n.JavaScriptCatalog`
+  and :class:`~django.views.i18n.JSONCatalog`.
+
 .. _removed-features-1.10:
 
 Features removed in 1.10

docs/topics/i18n/translation.txt

@@ -959,15 +959,76 @@ Django provides an integrated solution for these problems: It passes the
 translations into JavaScript, so you can call ``gettext``, etc., from within
 JavaScript.
 
+The main solution to these problems is the following ``JavaScriptCatalog`` view,
+which generates a JavaScript code library with functions that mimic the
+``gettext`` interface, plus an array of translation strings.
+
 .. _javascript_catalog-view:
 
-The ``javascript_catalog`` view
--------------------------------
+The ``JavaScriptCatalog`` view
+------------------------------
 
 .. module:: django.views.i18n
 
+.. versionadded:: 1.10
+
+.. class:: JavaScriptCatalog
+
+    A view that produces a JavaScript code library with functions that mimic
+    the ``gettext`` interface, plus an array of translation strings.
+
+    **Attributes**
+
+    .. attribute:: domain
+
+        Translation domain containing strings to add in the view output.
+        Defaults to ``'djangojs'``.
+
+    .. attribute:: packages
+
+        A list of :attr:`application names <django.apps.AppConfig.name>` among
+        installed applications. Those apps should contain a ``locale``
+        directory. All those catalogs plus all catalogs found in
+        :setting:`LOCALE_PATHS` (which are always included) are merged into one
+        catalog. Defaults to ``None``, which means that all available
+        translations from all :setting:`INSTALLED_APPS` are provided in the
+        JavaScript output.
+
+    **Example with default values**::
+
+        from django.views.i18n import JavaScriptCatalog
+
+        urlpatterns = [
+            url(r'^jsi18n/$', JavaScriptCatalog.as_view(), name='javascript-catalog'),
+        ]
+
+    **Example with custom packages**::
+
+        urlpatterns = [
+            url(r'^jsi18n/myapp/$',
+                JavaScriptCatalog.as_view(packages=['your.app.label']),
+                name='javascript-catalog'),
+        ]
+
+The precedence of translations is such that the packages appearing later in the
+``packages`` argument have higher precedence than the ones appearing at the
+beginning. This is important in the case of clashing translations for the same
+literal.
+
+If you use more than one ``JavaScriptCatalog`` view on a site and some of them
+define the same strings, the strings in the catalog that was loaded last take
+precedence.
+
+The ``javascript_catalog`` view
+-------------------------------
+
 .. function:: javascript_catalog(request, domain='djangojs', packages=None)
 
+.. deprecated:: 1.10
+
+    ``javascript_catalog()`` is deprecated in favor of
+    :class:`JavaScriptCatalog` and will be removed in Django 2.0.
+
 The main solution to these problems is the
 :meth:`django.views.i18n.javascript_catalog` view, which sends out a JavaScript
 code library with functions that mimic the ``gettext`` interface, plus an array
@@ -1209,6 +1270,37 @@ will render a conditional expression. This will evaluate to either a ``true``
 
 .. highlight:: python
 
+The ``JSONCatalog`` view
+------------------------
+
+.. versionadded:: 1.10
+
+.. class:: JSONCatalog
+
+    In order to use another client-side library to handle translations, you may
+    want to take advantage of the ``JSONCatalog`` view. It's similar to
+    :class:`~django.views.i18n.JavaScriptCatalog` but returns a JSON response.
+
+    See the documentation for :class:`~django.views.i18n.JavaScriptCatalog`
+    to learn about possible values and use of the ``domain`` and ``packages``
+    attributes.
+
+    The response format is as follows:
+
+    .. code-block:: text
+
+        {
+            "catalog": {
+                # Translations catalog
+            },
+            "formats": {
+                # Language formats for date, time, etc.
+            },
+            "plural": "..."  # Expression for plural forms, or null.
+        }
+
+    .. JSON doesn't allow comments so highlighting as JSON won't work here.
+
 The ``json_catalog`` view
 -------------------------
 
@@ -1216,6 +1308,11 @@ The ``json_catalog`` view
 
 .. function:: json_catalog(request, domain='djangojs', packages=None)
 
+.. deprecated:: 1.10
+
+    ``json_catalog()`` is deprecated in favor of :class:`JSONCatalog` and will
+    be removed in Django 2.0.
+
 In order to use another client-side library to handle translations, you may
 want to take advantage of the ``json_catalog()`` view. It's similar to
 :meth:`~django.views.i18n.javascript_catalog` but returns a JSON response.
@@ -1260,9 +1357,9 @@ The response format is as follows:
 Note on performance
 -------------------
 
-The :func:`~django.views.i18n.javascript_catalog` view generates the catalog
-from ``.mo`` files on every request. Since its output is constant — at least
-for a given version of a site — it's a good candidate for caching.
+The various JavaScript/JSON i18n views generate the catalog from ``.mo`` files
+on every request. Since its output is constant, at least for a given version
+of a site, it's a good candidate for caching.
 
 Server-side caching will reduce CPU load. It's easily implemented with the
 :func:`~django.views.decorators.cache.cache_page` decorator. To trigger cache
@@ -1271,12 +1368,14 @@ prefix, as shown in the example below, or map the view at a version-dependent
 URL::
 
     from django.views.decorators.cache import cache_page
-    from django.views.i18n import javascript_catalog
+    from django.views.i18n import JavaScriptCatalog
 
     # The value returned by get_version() must change when translations change.
-    @cache_page(86400, key_prefix='js18n-%s' % get_version())
-    def cached_javascript_catalog(request, domain='djangojs', packages=None):
-        return javascript_catalog(request, domain, packages)
+    urlpatterns = [
+        url(r'^jsi18n/$',
+            cache_page(86400, key_prefix='js18n-%s' % get_version())(JavaScriptCatalog.as_view()),
+            name='javascript-catalog'),
+    ]
 
 Client-side caching will save bandwidth and make your site load faster. If
 you're using ETags (:setting:`USE_ETAGS = True <USE_ETAGS>`), you're already
@@ -1286,13 +1385,15 @@ whenever you restart your application server::
 
     from django.utils import timezone
     from django.views.decorators.http import last_modified
-    from django.views.i18n import javascript_catalog
+    from django.views.i18n import JavaScriptCatalog
 
     last_modified_date = timezone.now()
 
-    @last_modified(lambda req, **kw: last_modified_date)
-    def cached_javascript_catalog(request, domain='djangojs', packages=None):
-        return javascript_catalog(request, domain, packages)
+    urlpatterns = [
+        url(r'^jsi18n/$',
+            last_modified(lambda req, **kw: last_modified_date)(JavaScriptCatalog.as_view()),
+            name='javascript-catalog'),
+    ]
 
 You can even pre-generate the JavaScript catalog as part of your deployment
 procedure and serve it as a static file. This radical technique is implemented

tests/view_tests/templates/old_jsi18n-multi-catalogs.html

+<html>
+<head>
+  <script type="text/javascript" src="/old_jsi18n/app1/"></script>
+  <script type="text/javascript" src="/old_jsi18n/app2/"></script>
+<body>
+  <p id="app1string">
+    <script type="text/javascript">
+      document.write(gettext('this app1 string is to be translated'))
+    </script>
+  </p>
+  <p id="app2string">
+    <script type="text/javascript">
+      document.write(gettext('this app2 string is to be translated'))
+    </script>
+  </p>
+</body>
+</html>

tests/view_tests/templates/old_jsi18n.html

+<html>
+<head>
+  <script type="text/javascript" src="/old_jsi18n_admin/"></script>
+</head>
+
+<body>
+  <p id="gettext">
+    <script type="text/javascript">
+    document.write(gettext("Remove"));
+    </script>
+  </p>
+
+  <p id="ngettext_sing">
+    <script type="text/javascript">
+    document.write(interpolate(ngettext("%s item", "%s items", 1), [1]));
+    </script>
+  </p>
+
+  <p id="ngettext_plur">
+    <script type="text/javascript">
+    document.write(interpolate(ngettext("%s item", "%s items", 455), [455]));
+    </script>
+  </p>
+
+  <p id="pgettext">
+    <script type="text/javascript">
+    document.write(pgettext("verb", "May"));
+    </script>
+  </p>
+
+  <p id="npgettext_sing">
+    <script type="text/javascript">
+    document.write(interpolate(npgettext("search", "%s result", "%s results", 1), [1]));
+    </script>
+  </p>
+
+  <p id="npgettext_plur">
+    <script type="text/javascript">
+    document.write(interpolate(npgettext("search", "%s result", "%s results", 455), [455]));
+    </script>
+  </p>
+
+</body>
+</html>

tests/view_tests/tests/test_i18n.py

@@ -167,6 +167,13 @@ class I18NTests(TestCase):
         )
         self.assertRedirects(response, '/en/translated/')
 
+
+@override_settings(ROOT_URLCONF='view_tests.urls')
+class JsI18NTests(SimpleTestCase):
+    """
+    Tests views in django/views/i18n.py that need to change
+    settings.LANGUAGE_CODE.
+    """
     def test_jsi18n(self):
         """The javascript_catalog can be deployed with language settings"""
         for lang_code in ['es', 'fr', 'ru']:
@@ -185,6 +192,13 @@ class I18NTests(TestCase):
                     # Message with context (msgctxt)
                     self.assertContains(response, '"month name\\u0004May": "mai"', 1)
 
+    @override_settings(USE_I18N=False)
+    def test_jsi18n_USE_I18N_False(self):
+        response = self.client.get('/jsi18n/')
+        # default plural function
+        self.assertContains(response, 'django.pluralidx = function(count) { return (count == 1) ? 0 : 1; };')
+        self.assertNotContains(response, 'var newcatalog =')
+
     def test_jsoni18n(self):
         """
         The json_catalog returns the language catalog and settings as JSON.
@@ -199,14 +213,6 @@ class I18NTests(TestCase):
             self.assertIn('DATETIME_FORMAT', data['formats'])
             self.assertEqual(data['plural'], '(n != 1)')
 
-
-@override_settings(ROOT_URLCONF='view_tests.urls')
-class JsI18NTests(SimpleTestCase):
-    """
-    Tests django views in django/views/i18n.py that need to change
-    settings.LANGUAGE_CODE.
-    """
-
     def test_jsi18n_with_missing_en_files(self):
         """
         The javascript_catalog shouldn't load the fallback language in the
@@ -304,7 +310,7 @@ class JsI18NTests(SimpleTestCase):
 @override_settings(ROOT_URLCONF='view_tests.urls')
 class JsI18NTestsMultiPackage(SimpleTestCase):
     """
-    Tests for django views in django/views/i18n.py that need to change
+    Tests views in django/views/i18n.py that need to change
     settings.LANGUAGE_CODE and merge JS translation from several packages.
     """
     @modify_settings(INSTALLED_APPS={'append': ['view_tests.app1', 'view_tests.app2']})

tests/view_tests/urls.py

@@ -72,19 +72,35 @@ urlpatterns = [
     url(r'technical404/$', views.technical404, name="my404"),
     url(r'classbased404/$', views.Http404View.as_view()),
 
+    # deprecated i18n views
+    url(r'^old_jsi18n/$', i18n.javascript_catalog, js_info_dict),
+    url(r'^old_jsi18n/app1/$', i18n.javascript_catalog, js_info_dict_app1),
+    url(r'^old_jsi18n/app2/$', i18n.javascript_catalog, js_info_dict_app2),
+    url(r'^old_jsi18n/app5/$', i18n.javascript_catalog, js_info_dict_app5),
+    url(r'^old_jsi18n_english_translation/$', i18n.javascript_catalog, js_info_dict_english_translation),
+    url(r'^old_jsi18n_multi_packages1/$', i18n.javascript_catalog, js_info_dict_multi_packages1),
+    url(r'^old_jsi18n_multi_packages2/$', i18n.javascript_catalog, js_info_dict_multi_packages2),
+    url(r'^old_jsi18n_admin/$', i18n.javascript_catalog, js_info_dict_admin),
+    url(r'^old_jsi18n_template/$', views.old_jsi18n),
+    url(r'^old_jsi18n_multi_catalogs/$', views.old_jsi18n_multi_catalogs),
+    url(r'^old_jsoni18n/$', i18n.json_catalog, js_info_dict),
+
     # i18n views
     url(r'^i18n/', include('django.conf.urls.i18n')),
-    url(r'^jsi18n/$', i18n.javascript_catalog, js_info_dict),
-    url(r'^jsi18n/app1/$', i18n.javascript_catalog, js_info_dict_app1),
-    url(r'^jsi18n/app2/$', i18n.javascript_catalog, js_info_dict_app2),
-    url(r'^jsi18n/app5/$', i18n.javascript_catalog, js_info_dict_app5),
-    url(r'^jsi18n_english_translation/$', i18n.javascript_catalog, js_info_dict_english_translation),
-    url(r'^jsi18n_multi_packages1/$', i18n.javascript_catalog, js_info_dict_multi_packages1),
-    url(r'^jsi18n_multi_packages2/$', i18n.javascript_catalog, js_info_dict_multi_packages2),
-    url(r'^jsi18n_admin/$', i18n.javascript_catalog, js_info_dict_admin),
+    url(r'^jsi18n/$', i18n.JavaScriptCatalog.as_view(packages=['view_tests'])),
+    url(r'^jsi18n/app1/$', i18n.JavaScriptCatalog.as_view(packages=['view_tests.app1'])),
+    url(r'^jsi18n/app2/$', i18n.JavaScriptCatalog.as_view(packages=['view_tests.app2'])),
+    url(r'^jsi18n/app5/$', i18n.JavaScriptCatalog.as_view(packages=['view_tests.app5'])),
+    url(r'^jsi18n_english_translation/$', i18n.JavaScriptCatalog.as_view(packages=['view_tests.app0'])),
+    url(r'^jsi18n_multi_packages1/$',
+        i18n.JavaScriptCatalog.as_view(packages=['view_tests.app1', 'view_tests.app2'])),
+    url(r'^jsi18n_multi_packages2/$',
+        i18n.JavaScriptCatalog.as_view(packages=['view_tests.app3', 'view_tests.app4'])),
+    url(r'^jsi18n_admin/$',
+        i18n.JavaScriptCatalog.as_view(packages=['django.contrib.admin', 'view_tests'])),
     url(r'^jsi18n_template/$', views.jsi18n),
     url(r'^jsi18n_multi_catalogs/$', views.jsi18n_multi_catalogs),
-    url(r'^jsoni18n/$', i18n.json_catalog, js_info_dict),
+    url(r'^jsoni18n/$', i18n.JSONCatalog.as_view(packages=['view_tests'])),
 
     # Static views
     url(r'^site_media/(?P<path>.*)$', static.serve, {'document_root': media_dir}),

tests/view_tests/views.py

@@ -85,8 +85,16 @@ def jsi18n(request):
     return render(request, 'jsi18n.html')
 
 
+def old_jsi18n(request):
+    return render(request, 'old_jsi18n.html')
+
+
 def jsi18n_multi_catalogs(request):
-    return render(render, 'jsi18n-multi-catalogs.html')
+    return render(request, 'jsi18n-multi-catalogs.html')
+
+
+def old_jsi18n_multi_catalogs(request):
+    return render(request, 'old_jsi18n-multi-catalogs.html')
 
 
 def raises_template_does_not_exist(request, path='i_dont_exist.html'):