From 1742fd08f5e2f7353b67b58b4ef9185121ce300e Mon Sep 17 00:00:00 2001
From: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon, 25 Feb 2013 22:29:38 +0100
Subject: [PATCH] [1.5.x] Fixed #6195 -- Documented caching options for
 javascript_catalog.

Backport of 0836670 from master
---
 docs/topics/conditional-view-processing.txt |  2 +-
 docs/topics/i18n/translation.txt            | 46 +++++++++++++++++++++
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/docs/topics/conditional-view-processing.txt b/docs/topics/conditional-view-processing.txt
index 1979e89c31b..caa73761897 100644
--- a/docs/topics/conditional-view-processing.txt
+++ b/docs/topics/conditional-view-processing.txt
@@ -27,7 +27,7 @@ instead of a full response, telling the client that nothing has changed.
 When you need more fine-grained control you may use per-view conditional
 processing functions.
 
-.. conditional-decorators:
+.. _conditional-decorators:
 
 The ``condition`` decorator
 ===========================
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index a637d2998e7..3923a585f7c 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -918,6 +918,52 @@ 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).
 
+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.
+
+Server-side caching will reduce CPU load. It's easily implemented with the
+:func:`~django.views.decorators.cache.cache_page` decorator. To trigger cache
+invalidation when your translations change, provide a version-dependant key
+prefix, as shown in the example below, or map the view at a version-dependant
+URL.
+
+.. code-block:: python
+
+    from django.views.decorators.cache import cache_page
+    from django.views.i18n import javascript_catalog
+
+    # 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)
+
+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
+covered. Otherwise, you can apply :ref:`conditional decorators
+<conditional-decorators>`. In the following example, the cache is invalidated
+whenever your restart your application server.
+
+.. code-block:: python
+
+    from django.utils import timezone
+    from django.views.decorators.http import last_modified
+    from django.views.i18n import javascript_catalog
+
+    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)
+
+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
+in django-statici18n_.
+
+.. _django-statici18n: http://django-statici18n.readthedocs.org/en/latest/
+
 .. _url-internationalization:
 
 Internationalization: in URL patterns