From df5a8a07fc909e37016889bc1d37c53c90e747c5 Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Sat, 18 May 2013 11:20:02 -0400
Subject: [PATCH] [1.5.x] Fixed #20335 - Documented the {% language %} template
 tag.

Thanks bmispelon for the suggestion and djangsters for the patch.

Backport of 96cabba808 from master
---
 docs/topics/i18n/translation.txt | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index a5cf9c1410b..bb38c919661 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -694,6 +694,31 @@ or with the ``{#`` ... ``#}`` :ref:`one-line comment constructs <template-commen
         msgid "Ambiguous translatable block of text"
         msgstr ""
 
+.. templatetag:: language
+
+Switching language in templates
+-------------------------------
+
+If you want to select a language within a template, you can use the
+``language`` template tag:
+
+.. code-block:: html+django
+
+    {% load i18n %}
+
+    {% get_current_language as LANGUAGE_CODE %}
+    <!-- Current language: {{ LANGUAGE_CODE }} -->
+    <p>{% trans "Welcome to our page" %}</p>
+
+    {% language 'en' %}
+        {% get_current_language as LANGUAGE_CODE %}
+        <!-- Current language: {{ LANGUAGE_CODE }} -->
+        <p>{% trans "Welcome to our page" %}</p>
+    {% endlanguage %}
+
+While the first occurrence of "Welcome to our page" uses the current language,
+the second will always be in English.
+
 .. _template-translation-vars:
 
 Other tags
@@ -1098,13 +1123,11 @@ active language. Example::
 
 .. _reversing_in_templates:
 
-.. templatetag:: language
-
 Reversing in templates
 ----------------------
 
 If localized URLs get reversed in templates they always use the current
-language. To link to a URL in another language use the ``language``
+language. To link to a URL in another language use the :ttag:`language`
 template tag. It enables the given language in the enclosed template section:
 
 .. code-block:: html+django