Fixed #7980 - Improved i18n framework to support locale aware formatting (dates and numbers) and form processing.

Thanks to Marc Garcia for working on this during his Google Summer of Code 2009!

Additionally fixes #1061, #2203, #3940, #5526, #6449, #6231, #6693, #6783, #9366 and #10891.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11964 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jannis Leidel 2009-12-22 17:58:49 +00:00
parent 6632739e94
commit 9233d04265
128 changed files with 2304 additions and 346 deletions

View file

@ -62,6 +62,18 @@ their deprecation, as per the :ref:`Django deprecation policy
backwards compatibility. These have been deprecated since the 1.2
release.
* ``django.utils.translation.get_date_formats()`` and
``django.utils.translation.get_partial_date_formats()``. These
functions are replaced by the new locale aware formatting; use
``django.utils.formats.get_format()`` to get the appropriate
formats.
* In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``,
``DEFAULT_TIME_INPUT_FORMATS`` and
``DEFAULT_DATETIME_INPUT_FORMATS``. Use
``django.utils.formats.get_format()`` to get the appropriate
formats.
* 2.0
* ``django.views.defaults.shortcut()``. This function has been moved
to ``django.contrib.contenttypes.views.shortcut()`` as part of the

View file

@ -372,12 +372,32 @@ DATE_FORMAT
Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``)
The default formatting to use for date fields on Django admin change-list
pages -- and, possibly, by other parts of the system. See
:ttag:`allowed date format strings <now>`.
The default formatting to use for date fields in any part of the system.
Note that if ``USE_L10N`` is set to ``True``, then locale format will
be applied. See :ttag:`allowed date format strings <now>`.
See also ``DATETIME_FORMAT``, ``TIME_FORMAT``, ``YEAR_MONTH_FORMAT``
and ``MONTH_DAY_FORMAT``.
See also ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``SHORT_DATE_FORMAT``.
.. setting:: DATE_INPUT_FORMATS
DATE_INPUT_FORMATS
------------------
Default::
('%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', '%b %d %Y',
'%b %d, %Y', '%d %b %Y', '%d %b, %Y', '%B %d %Y',
'%B %d, %Y', '%d %B %Y', '%d %B, %Y')
A tuple of formats that will be accepted when inputting data on a date
field. Formats will be tried in order, using the first valid.
Note that these format strings are specified in Python's datetime_ module
syntax, that is different from the one used by Django for formatting dates
to be displayed.
See also ``DATETIME_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``.
.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior
.. setting:: DATETIME_FORMAT
@ -386,12 +406,32 @@ DATETIME_FORMAT
Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``)
The default formatting to use for datetime fields on Django admin change-list
pages -- and, possibly, by other parts of the system. See
:ttag:`allowed date format strings <now>`.
The default formatting to use for datetime fields in any part of the system.
Note that if ``USE_L10N`` is set to ``True``, then locale format will
be applied. See :ttag:`allowed date format strings <now>`.
See also ``DATE_FORMAT``, ``DATETIME_FORMAT``, ``TIME_FORMAT``,
``YEAR_MONTH_FORMAT`` and ``MONTH_DAY_FORMAT``.
See also ``DATE_FORMAT``, ``TIME_FORMAT`` and ``SHORT_DATETIME_FORMAT``.
.. setting:: DATETIME_INPUT_FORMATS
DATETIME_INPUT_FORMATS
----------------------
Default::
('%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d',
'%m/%d/%Y %H:%M:%S', '%m/%d/%Y %H:%M', '%m/%d/%Y',
'%m/%d/%y %H:%M:%S', '%m/%d/%y %H:%M', '%m/%d/%y')
A tuple of formats that will be accepted when inputting data on a datetime
field. Formats will be tried in order, using the first valid.
Note that these format strings are specified in Python's datetime_ module
syntax, that is different from the one used by Django for formatting dates
to be displayed.
See also ``DATE_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``.
.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior
.. setting:: DEBUG
@ -431,6 +471,14 @@ will be suppressed, and exceptions will propagate upwards. This can
be useful for some test setups, and should never be used on a live
site.
.. setting:: DECIMAL_SEPARATOR
DECIMAL_SEPARATOR
-----------------
Default: ``'.'`` (Dot)
Default decimal separator used when formatting decimal numbers.
.. setting:: DEFAULT_CHARSET
@ -680,6 +728,21 @@ system's standard umask.
.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html
.. setting:: FIRST_DAY_OF_WEEK
FIRST_DAY_OF_WEEK
-----------------
Default: ``0`` (Sunday)
Number representing the first day of the week. This is especially useful
when displaying a calendar. This value is only used when not using
format internationalization, or when a format cannot be found for the
current locale.
The value must be an integer from 0 to 6, where 0 means Sunday, 1 means
Monday and so on.
.. setting:: FIXTURE_DIRS
FIXTURE_DIRS
@ -701,6 +764,34 @@ environment variable in any HTTP request. This setting can be used to override
the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version
of the preferred value or not supplied at all.
.. setting:: FORMAT_MODULE_PATH
FORMAT_MODULE_PATH
------------------
Default: ``None``
A full Python path to a Python package that contains format definitions for
project locales. If not ``None``, Django will check for a ``formats.py``
file, under the directory named as the current locale, and will use the
formats defined on this file.
For example, if ``FORMAT_MODULE_PATH`` is set to ``mysite.formats``, and
current language is ``en`` (English), Django will expect a directory tree
like::
mysite/
formats/
__init__.py
en/
__init__.py
formats.py
Available formats are ``DATE_FORMAT``, ``TIME_FORMAT``, ``DATETIME_FORMAT``,
``YEAR_MONTH_FORMAT``, ``MONTH_DAY_FORMAT``, ``SHORT_DATE_FORMAT``,
``SHORT_DATETIME_FORMAT``, ``FIRST_DAY_OF_WEEK``, ``DECIMAL_SEPARATOR``,
``THOUSAND_SEPARATOR`` and ``NUMBER_GROUPING``.
.. setting:: IGNORABLE_404_ENDS
IGNORABLE_404_ENDS
@ -845,7 +936,7 @@ LOGIN_URL
Default: ``'/accounts/login/'``
The URL where requests are redirected for login, specially when using the
The URL where requests are redirected for login, especially when using the
:func:`~django.contrib.auth.decorators.login_required` decorator.
.. setting:: LOGOUT_URL
@ -970,6 +1061,21 @@ locales have different formats. For example, U.S. English would say
See :ttag:`allowed date format strings <now>`. See also ``DATE_FORMAT``,
``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``YEAR_MONTH_FORMAT``.
.. setting:: NUMBER_GROUPING
NUMBER_GROUPING
----------------
Default: ``0``
Number of digits grouped together on the integer part of a number. Common use
is to display a thousand separator. If this setting is ``0``, then, no grouping
will be applied to the number. If this setting is greater than ``0`` then the
setting ``THOUSAND_SEPARATOR`` will be used as the separator between those
groups.
See also ``THOUSAND_SEPARATOR``
.. setting:: PREPEND_WWW
PREPEND_WWW
@ -1173,6 +1279,32 @@ Default: ``False``
Whether to save the session data on every request. See
:ref:`topics-http-sessions`.
.. setting:: SHORT_DATE_FORMAT
SHORT_DATE_FORMAT
-----------------
Default: ``m/d/Y`` (e.g. ``12/31/2003``)
An available formatting that can be used for date fields on templates.
Note that if ``USE_L10N`` is set to ``True``, then locale format will
be applied. See :ttag:`allowed date format strings <now>`.
See also ``DATE_FORMAT`` and ``SHORT_DATETIME_FORMAT``.
.. setting:: SHORT_DATETIME_FORMAT
SHORT_DATETIME_FORMAT
---------------------
Default: ``m/d/Y P`` (e.g. ``12/31/2003 4 p.m.``)
An available formatting that can be used for datetime fields on templates.
Note that if ``USE_L10N`` is set to ``True``, then locale format will
be applied. See :ttag:`allowed date format strings <now>`.
See also ``DATE_FORMAT`` and ``SHORT_DATETIME_FORMAT``.
.. setting:: SITE_ID
SITE_ID
@ -1277,6 +1409,18 @@ The name of the method to use for starting the test suite. See
.. _Testing Django Applications: ../testing/
.. setting:: THOUSAND_SEPARATOR
THOUSAND_SEPARATOR
------------------
Default ``,`` (Comma)
Default thousand separator used when formatting numbers. This setting is
used only when ``NUMBER_GROUPPING`` is set.
See also ``NUMBER_GROUPPING``, ``DECIMAL_SEPARATOR``
.. setting:: TIME_FORMAT
TIME_FORMAT
@ -1284,12 +1428,28 @@ TIME_FORMAT
Default: ``'P'`` (e.g. ``4 p.m.``)
The default formatting to use for time fields on Django admin change-list
pages -- and, possibly, by other parts of the system. See
:ttag:`allowed date format strings <now>`.
The default formatting to use for time fields in any part of the system.
Note that if ``USE_L10N`` is set to ``True``, then locale format will
be applied. See :ttag:`allowed date format strings <now>`.
See also ``DATE_FORMAT``, ``DATETIME_FORMAT``, ``TIME_FORMAT``,
``YEAR_MONTH_FORMAT`` and ``MONTH_DAY_FORMAT``.
See also ``DATE_FORMAT`` and ``DATETIME_FORMAT``.
.. setting:: TIME_INPUT_FORMATS
TIME_INPUT_FORMATS
------------------
Default: ``('%H:%M:%S', '%H:%M')``
A tuple of formats that will be accepted when inputting data on a time
field. Formats will be tried in order, using the first valid.
Note that these format strings are specified in Python's datetime_ module
syntax, that is different from the one used by Django for formatting dates
to be displayed.
See also ``DATE_INPUT_FORMATS`` and ``DATETIME_INPUT_FORMATS``.
.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior
.. setting:: TIME_ZONE
@ -1344,6 +1504,19 @@ A boolean that specifies whether to output the "Etag" header. This saves
bandwidth but slows down performance. This is only used if ``CommonMiddleware``
is installed (see :ref:`topics-http-middleware`).
.. setting:: USE_L10N
USE_L10N
--------
Default ``False``
A boolean that specifies if data will be localized by default or not. If this
is set to ``True``, e.g. Django will display numbers and dates using the
format of the current locale.
See also ``USE_I18N`` and ``LANGUAGE_CODE``
.. setting:: USE_I18N
USE_I18N
@ -1356,6 +1529,22 @@ enabled. This provides an easy way to turn it off, for performance. If this is
set to ``False``, Django will make some optimizations so as not to load the
internationalization machinery.
See also ``USE_L10N``
.. setting:: USE_THOUSAND_SEPARATOR
USE_THOUSAND_SEPARATOR
----------------------
Default ``False``
A boolean that specifies wheter to display numbers using a thousand separator.
If this is set to ``True``, Django will use values from ``THOUSAND_SEPARATOR``
and ``NUMBER_GROUPING`` from current locale, to format the number.
``USE_L10N`` must be set to ``True``, in order to format numbers.
See also ``THOUSAND_SEPARATOR`` and ``NUMBER_GROUPING``.
.. setting:: YEAR_MONTH_FORMAT
YEAR_MONTH_FORMAT

View file

@ -1047,7 +1047,12 @@ If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces
date
~~~~
Formats a date according to the given format (same as the `now`_ tag).
Formats a date according to the given format.
Given format can be one of the predefined ones ``DATE_FORMAT``,
``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``,
or a custom format, same as the `now`_ tag. Note that predefined formats may
vary depending on the current locale.
For example::
@ -1062,7 +1067,7 @@ When used without a format string::
{{ value|date }}
...the formatting string defined in the :setting:`DATE_FORMAT` setting will be
used.
used, without applying any localization.
.. templatefilter:: default
@ -1610,7 +1615,11 @@ output will be ``"Joel is a slug"``.
time
~~~~
Formats a time according to the given format (same as the `now`_ tag).
Formats a time according to the given format.
Given format can be the predefined one ``TIME_FORMAT``, or a custom format,
same as the `now`_ tag. Note that the predefined format is locale depending.
The time filter will only accept parameters in the format string that relate
to the time of day, not the date (for obvious reasons). If you need to
format a date, use the `date`_ filter.
@ -1627,7 +1636,7 @@ When used without a format string::
{{ value|time }}
...the formatting string defined in the :setting:`TIME_FORMAT` setting will be
used.
used, without aplying any localization.
.. templatefilter:: timesince

View file

@ -318,6 +318,41 @@ For more information, see the full
:ref:`messages documentation <ref-contrib-messages>`. You should begin to
update your code to use the new API immediately.
Date format helper functions
----------------------------
``django.utils.translation.get_date_formats()`` and
``django.utils.translation.get_partial_date_formats()`` have been deprecated
in favor of the appropriate calls to ``django.utils.formats.get_format()``
which is locale aware when :setting:`USE_L10N` is set to ``True``, and falls
back to default settings if set to ``False``.
To get the different date formats, instead of writing::
from django.utils.translation import get_date_formats
date_format, datetime_format, time_format = get_date_formats()
use::
from django.utils import formats
date_format = formats.get_format('DATE_FORMAT')
datetime_format = formats.get_format('DATETIME_FORMAT')
time_format = formats.get_format('TIME_FORMAT')
or, when directly formatting a date value::
from django.utils import formats
value_formatted = formats.date_format(value, 'DATETIME_FORMAT')
The same applies to the globals found in ``django.forms.fields``:
* ``DEFAULT_DATE_INPUT_FORMATS``
* ``DEFAULT_TIME_INPUT_FORMATS``
* ``DEFAULT_DATETIME_INPUT_FORMATS``
Use ``django.utils.formats.get_format()`` to get the appropriate formats.
What's new in Django 1.2
========================
@ -440,3 +475,13 @@ The ``test`` subcommand of ``django-admin.py``, and the ``runtests.py`` script
used to run Django's own test suite, support a new ``--failfast`` option.
When specified, this option causes the test runner to exit after
encountering a failure instead of continuing with the test run.
Improved localization
---------------------
Django's :ref:`internationalization framework <topics-i18n>` has been
expanded by locale aware formatting and form processing. That means, if
enabled, dates and numbers on templates will be displayed using the format
specified for the current locale. Django will also use localized formats
when parsing data in forms.
See :ref:`Format localization <format-localization>` for more details.

View file

@ -4,20 +4,20 @@
Internationalization
====================
Django has full support for internationalization of text in code and templates.
Here's how it works.
Django has full support for internationalization of text in code and
templates, and format localization of dates and numbers. Here's how it works.
Overview
========
The goal of internationalization is to allow a single Web application to offer
its content and functionality in multiple languages.
its content and functionality in multiple languages and locales.
You, the Django developer, can accomplish this goal by adding a minimal amount
of hooks to your Python code and templates. These hooks are called
**translation strings**. They tell Django: "This text should be translated into
the end user's language, if a translation for this text is available in that
language."
For text translation, you, the Django developer, can accomplish this goal by
adding a minimal amount of hooks to your Python code and templates. These hooks
are called **translation strings**. They tell Django: "This text should be
translated into the end user's language, if a translation for this text is
available in that language."
Django takes care of using these hooks to translate Web apps, on the fly,
according to users' language preferences.
@ -29,6 +29,12 @@ Essentially, Django does two things:
* It uses these hooks to translate Web apps for particular users according
to their language preferences.
For format localization, it's just necessary to set
:setting:`USE_L10N = True <USE_L10N>` in your settings file. If
:setting:`USE_L10N` is set to ``True``, Django will display
numbers and dates in the format of the current locale. That includes field
representation on templates, and allowed input formats on the admin.
If you don't need internationalization in your app
==================================================
@ -1074,3 +1080,53 @@ have been found to not support this command. Do not attempt to use Django
translation utilities with a ``gettext`` package if the command ``xgettext
--version`` entered at a Windows command prompt causes a popup window saying
"xgettext.exe has generated errors and will be closed by Windows".
.. _format-localization:
Format localization
===================
Django's formatting system is disabled by default. To enable it, it's necessay
to set :setting:`USE_L10N = True <USE_L10N>` in your settings file.
When using Django's formatting system, dates and numbers on templates will be
displayed using the format specified for the current locale. Two users
accessing the same content, but in different language, will see date and
number fields formatted in different ways, depending on the format for their
current locale.
Django will also use localized formats when parsing data in forms. That means
Django uses different formats for different locales when guessing the format
used by the user when inputting data on forms. Note that Django uses different
formats for displaying data, and for parsing it.
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, first thing to do, is to specify the path where you'll
place format files. To do that, just set your :setting:`FORMAT_MODULE_PATH`
setting to the the path (in the format ``'foo.bar.baz``) where format files
will exists.
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.