mirror of
https://github.com/django/django.git
synced 2024-12-30 21:16:26 +00:00
208 lines
6.1 KiB
Plaintext
208 lines
6.1 KiB
Plaintext
.. _format-localization:
|
|
|
|
===================
|
|
Format localization
|
|
===================
|
|
|
|
Overview
|
|
========
|
|
|
|
Django's formatting system is capable of displaying 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
|
|
startproject <startproject>` includes :setting:`USE_L10N = True <USE_L10N>`
|
|
for convenience. Note, however, that to enable number formatting with
|
|
thousand separators it is necessary to set :setting:`USE_THOUSAND_SEPARATOR
|
|
= True <USE_THOUSAND_SEPARATOR>` in your settings file. Alternatively, you
|
|
could use :tfilter:`intcomma` to format numbers in your template.
|
|
|
|
.. 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
|
|
~~~~~~~~
|
|
|
|
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
|
|
~~~~~~~~
|
|
|
|
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
|
|
~~~~~~~~~~
|
|
|
|
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.
|
|
|
|
.. _custom-format-files:
|
|
|
|
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.
|
|
|
|
|
|
.. versionchanged:: 1.8
|
|
|
|
The ability to specify :setting:`FORMAT_MODULE_PATH` as a list was added.
|
|
Previously, only a single string value was supported.
|
|
|
|
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',
|
|
'some_app.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::
|
|
|
|
from __future__ import unicode_literals
|
|
|
|
THOUSAND_SEPARATOR = '\xa0'
|
|
|
|
to use a non-breaking space (Unicode ``00A0``) as a thousand separator,
|
|
instead of the default for English, a comma.
|
|
|
|
Limitations of the provided locale formats
|
|
==========================================
|
|
|
|
Some locales use context-sensitive formats for numbers, which Django's
|
|
localization system cannot handle automatically.
|
|
|
|
Switzerland (German)
|
|
--------------------
|
|
|
|
The Swiss number formatting depends on the type of number that is being
|
|
formatted. For monetary values, a comma is used as the thousand separator and
|
|
a decimal point for the decimal separator. For all other numbers, a comma is
|
|
used as decimal separator and a space as thousand separator. The locale format
|
|
provided by Django uses the generic separators, a comma for decimal and a space
|
|
for thousand separators.
|