From 3c06e2101bbb05863a5325dc8b6fb1979384f899 Mon Sep 17 00:00:00 2001
From: Jannis Leidel <jannis@leidel.info>
Date: Mon, 15 Mar 2010 12:16:37 +0000
Subject: [PATCH] Fixed #13014 - Added section about how to use the language
 code with fragement caching. Thanks for the initial patch, fgutierrez.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12787 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/topics/cache.txt                     | 33 ++++++++++++++++++++---
 docs/topics/i18n/internationalization.txt |  2 ++
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 6c8f1346bb..025e910212 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -320,6 +320,8 @@ time, rather than ``CACHE_MIDDLEWARE_SECONDS``. Using the decorators in
 the ``never_cache`` decorator). See the `using other headers`__ section for
 more on these decorators.
 
+.. _i18n-cache-key:
+
 .. versionadded:: 1.2
 
 If :setting:`USE_I18N` is set to ``True`` then the generated cache key will
@@ -413,7 +415,9 @@ the ``cache`` template tag. To give your template access to this tag, put
 
 The ``{% cache %}`` template tag caches the contents of the block for a given
 amount of time. It takes at least two arguments: the cache timeout, in seconds,
-and the name to give the cache fragment. For example::
+and the name to give the cache fragment. For example:
+
+.. code-block:: html+django
 
     {% load cache %}
     {% cache 500 sidebar %}
@@ -424,7 +428,9 @@ Sometimes you might want to cache multiple copies of a fragment depending on
 some dynamic data that appears inside the fragment. For example, you might want a
 separate cached copy of the sidebar used in the previous example for every user
 of your site. Do this by passing additional arguments to the ``{% cache %}``
-template tag to uniquely identify the cache fragment::
+template tag to uniquely identify the cache fragment:
+
+.. code-block:: html+django
 
     {% load cache %}
     {% cache 500 sidebar request.user.username %}
@@ -434,10 +440,29 @@ template tag to uniquely identify the cache fragment::
 It's perfectly fine to specify more than one argument to identify the fragment.
 Simply pass as many arguments to ``{% cache %}`` as you need.
 
+If :setting:`USE_I18N` is set to ``True`` the per-site middleware cache will
+:ref:`respect the active language<i18n-cache-key>`. For the ``cache`` template
+tag you could use one of the
+:ref:`translation-specific variables<template-translation-vars>` available in
+templates to archieve the same result:
+
+.. code-block:: html+django
+
+    {% load i18n %}
+    {% load cache %}
+
+    {% get_current_language as LANGUAGE_CODE %}
+
+    {% cache 600 welcome LANGUAGE_CODE %}
+        {% trans "Welcome to example.com" %}
+    {% endcache %}
+
 The cache timeout can be a template variable, as long as the template variable
 resolves to an integer value. For example, if the template variable
 ``my_timeout`` is set to the value ``600``, then the following two examples are
-equivalent::
+equivalent:
+
+.. code-block:: html+django
 
     {% cache 600 sidebar %} ... {% endcache %}
     {% cache my_timeout sidebar %} ... {% endcache %}
@@ -448,6 +473,8 @@ timeout in a variable, in one place, and just reuse that value.
 The low-level cache API
 =======================
 
+.. highlight:: python
+
 Sometimes, caching an entire rendered page doesn't gain you very much and is,
 in fact, inconvenient overkill.
 
diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt
index efbed044e8..721bb6a1dd 100644
--- a/docs/topics/i18n/internationalization.txt
+++ b/docs/topics/i18n/internationalization.txt
@@ -385,6 +385,8 @@ used, have in mind that the ``blocktrans`` construct is internally converted
 to an ``ungettext`` call. This means the same :ref:`notes regarding ungettext
 variables <pluralization-var-notes>` apply.
 
+.. _template-translation-vars:
+
 Each ``RequestContext`` has access to three translation-specific variables:
 
     * ``LANGUAGES`` is a list of tuples in which the first element is the