django/docs/topics/i18n/formatting.txt

.. _format-localization:

===================
Format localization
===================

.. versionadded:: 1.2

Overview
========

Django's formatting system is capable to display dates, times and numbers in templates using the format specified for the current :term:`locale <locale
name>`. It also handles localized input in forms.

When it's enabled, two users accessing the same content may see dates, times and
numbers formatted in different ways, depending on the formats for their current
locale.

The formatting system is disabled by default. To enable it, it's
necessary to set :setting:`USE_L10N = True <USE_L10N>` in your settings file.

.. note::

    The default :file:`settings.py` file created by :djadmin:`django-admin.py
    startproject <startproject>` includes :setting:`USE_L10N = True <USE_L10N>`
    for convenience.

.. note::

    There is also an independent but related :setting:`USE_I18N` setting that
    controls if Django should activate translation. See
    :doc:`/topics/i18n/translation` for more details.

Locale aware input in forms
===========================

When formatting is enabled, Django can use localized formats when parsing dates,
times and numbers in forms. That means it tries different formats for different
locales when guessing the format used by the user when inputting data on forms.

.. note::
    Django uses different formats for displaying data to those it uses for
    parsing data. Most notably, the formats for parsing dates can't use the
    ``%a`` (abbreviated weekday name), ``%A`` (full weekday name),
    ``%b`` (abbreviated month name), ``%B`` (full month name),
    or ``%p`` (AM/PM).

To enable a form field to localize input and output data simply use its
``localize`` argument::

    class CashRegisterForm(forms.Form):
       product = forms.CharField()
       revenue = forms.DecimalField(max_digits=4, decimal_places=2, localize=True)

.. _topic-l10n-templates:

Controlling localization in templates
=====================================

When you have enabled formatting with :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 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::

    {% load l10n %}

    {% localize on %}
        {{ value }}
    {% endlocalize %}

    {% localize off %}
        {{ value }}
    {% endlocalize %}

.. note::

    The value of :setting:`USE_L10N` isn't respected inside of a
    ``{% localize %}`` block.

See :tfilter:`localize` and :tfilter:`unlocalize` for template filters 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::

    {% load l10n %}

    {{ 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::

    {% load l10n %}

    {{ 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.

Creating custom format files
============================

Django provides format definitions for many locales, but sometimes you might
want to create your own, because a format files doesn't exist for your locale,
or because you want to overwrite some of the values.

To use custom formats, specify the path where you'll place format files first.
To do that, just set your :setting:`FORMAT_MODULE_PATH` setting to the package
where format files will exist, for instance::

    FORMAT_MODULE_PATH = 'mysite.formats'

Files are not placed directly in this directory, but in a directory named as
the locale, and must be named ``formats.py``.

To customize the English formats, a structure like this would be needed::

    mysite/
        formats/
            __init__.py
            en/
                __init__.py
                formats.py

where :file:`formats.py` contains custom format definitions. For example::

    THOUSAND_SEPARATOR = ' '

to use a space as a thousand separator, instead of the default for English,
a comma.