1 files changed, 95 insertions, 2 deletions
diff --git a/docs/topics/i18n/localization.txt b/docs/topics/i18n/localization.txt
index 38d74e68e3..df89851039 100644
--- a/docs/topics/i18n/localization.txt
+++ b/docs/topics/i18n/localization.txt
@@ -2,11 +2,13 @@
 Localization
 ============
 
-This document covers two localization-related topics: `Creating language
-files`_ and `locale aware date, time and numbers input/output in forms`_
+This document covers three localization-related topics: `Creating language
+files`_ , `locale aware date, time and numbers input/output in forms`_,
+and `controlling localization in templates`_.
 
 .. _`Creating language files`: how-to-create-language-files_
 .. _`locale aware date, time and numbers input/output in forms`: format-localization_
+.. _`controlling localization in templates`: topic-l10n-templates
 
 .. seealso::
 
@@ -315,3 +317,94 @@ where :file:`formats.py` contains custom format definitions. For example::
 
 to use a space as a thousand separator, instead of the default for English,
 a comma.
+
+.. topic-l10n-templates:
+
+Controlling localization in templates
+=====================================
+
+When you have enabled localization using :setting:`USE_L10N`, Django
+will try to use a locale specific format whenever it outputs a value
+in a template.
+
+However, it may not always be appropriate to use localized values --
+for example, if you're outputting Javascript or XML that is designed
+to be machine-readable, you will always want unlocalized values. You
+may also want to use localization in selected templates, rather than
+using localization everywhere.
+
+To allow for fine control over the use of localization, Django
+provides a the ``l10n`` template library that contains the following
+tags and filters.
+
+Template tags
+-------------
+
+.. templatetag:: localize
+
+localize
+~~~~~~~~
+
+.. versionadded:: 1.3
+
+Enables or disables localization of template variables in the
+contained block.
+
+This tag allows a more fine grained control of localization than
+:setting:`USE_L10N`.
+
+To activate or deactivate localization for a template block, use::
+
+    {% localize on %}
+        {{ value }}
+    {% endlocalize %}
+
+    {% localize off %}
+        {{ value }}
+    {% endlocalize %}
+
+.. note::
+
+    The value of :setting:`USE_L10N` is not respected inside of a
+    `{% localize %}` block.
+
+See :tfilter:`localized` and :tfilter:`unlocalized` for a template filter that will
+do the same job on a per-variable basis.
+
+Template filters
+----------------
+
+.. templatefilter:: localize
+
+localize
+~~~~~~~~
+
+.. versionadded:: 1.3
+
+Forces localization of a single value.
+
+For example::
+
+    {{ value|localize }}
+
+To disable localization on a single value, use :tfilter:`unlocalize`. To control
+localization over a large section of a template, use the :ttag:`localize` template
+tag.
+
+
+.. templatefilter:: unlocalize
+
+unlocalize
+~~~~~~~~~~
+
+.. versionadded:: 1.3
+
+Forces a single value to be printed without localization.
+
+For example::
+
+    {{ value|unlocalize }}
+
+To force localization of a single value, use :tfilter:`localize`. To
+control localization over a large section of a template, use the
+:ttag:`localize` template tag.