Permalink
Browse files

[soc2009/i18n] Date filter allowed to use predefined formats, improve…

…d fallbacks on getting formats, and documentation added.

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/i18n-improvements@11231 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 0f205b9 commit c52ae07453a5556ba255aa115f2a4e8f56c7fd73 @datapythonista datapythonista committed Jul 13, 2009
Showing with 110 additions and 32 deletions.
  1. +11 −5 django/template/defaultfilters.py
  2. +15 −10 django/utils/formats.py
  3. +13 −5 django/views/i18n.py
  4. +11 −4 docs/ref/templates/builtins.txt
  5. +60 −8 docs/topics/i18n.txt
@@ -18,7 +18,7 @@
from django.utils.translation import ugettext, ungettext
from django.utils.encoding import force_unicode, iri_to_uri
from django.utils.safestring import mark_safe, SafeData
-from django.utils.formats import number_format
+from django.utils.formats import date_format, number_format
register = Library()
@@ -685,9 +685,12 @@ def date(value, arg=None):
if arg is None:
arg = settings.DATE_FORMAT
try:
- return format(value, arg)
+ return date_format(value, arg)
except AttributeError:
- return ''
+ try:
+ return format(value, arg)
+ except AttributeError:
+ return ''
date.is_safe = False
def time(value, arg=None):
@@ -698,9 +701,12 @@ def time(value, arg=None):
if arg is None:
arg = settings.TIME_FORMAT
try:
- return time_format(value, arg)
+ return date_format(value, arg)
except AttributeError:
- return ''
+ try:
+ return time_format(value, arg)
+ except AttributeError:
+ return ''
time.is_safe = False
def timesince(value, arg=None):
@@ -15,35 +15,40 @@ def getformat_null(format_type):
"""
return getattr(settings, format_type)
-def formats_module():
+def project_formats_module():
"""
- Returns the formats module for the current locale. It can be the
- custom one from the user, or Django's default.
+ Returns the formats module for the current locale, defined
+ on the project
"""
if settings.FORMAT_MODULE_PATH:
try:
return import_module('.formats', '%s.%s' % (settings.FORMAT_MODULE_PATH, get_language()))
except ImportError:
pass
+ return None
+def django_formats_module():
+ """
+ Returns the formats module for the current locale, defined
+ on Django
+ """
try:
return import_module('.formats', 'django.conf.locale.%s' % get_language())
except ImportError:
return None
-
def getformat_real(format_type):
"""
For a specific format type, returns the format for the
current language (locale) defaulting to the format on settings.
format_type is the name of the format, for example 'DATE_FORMAT'
"""
- module = formats_module()
- if module:
- try:
- return getattr(module, format_type)
- except AttributeError:
- pass
+ for module in (project_formats_module(), django_formats_module()):
+ if module:
+ try:
+ return getattr(module, format_type)
+ except AttributeError:
+ pass
return getformat_null(format_type)
# getformat will just return the value on setings if
View
@@ -3,7 +3,7 @@
from django.utils import importlib
from django.utils.translation import check_for_language, activate, to_locale, get_language
from django.utils.text import javascript_quote
-from django.utils.formats import formats_module
+from django.utils.formats import project_formats_module, django_formats_module
import os
import gettext as gettext_module
@@ -37,11 +37,19 @@ def get_formats():
"""
Returns an iterator over all formats in formats file
"""
- module = formats_module()
+ FORMAT_SETTINGS = ('DATE_FORMAT', 'DATETIME_FORMAT', 'TIME_FORMAT',
+ 'YEAR_MONTH_FORMAT', 'MONTH_DAY_FORMAT', 'SHORT_DATE_FORMAT',
+ 'SHORT_DATETIME_FORMAT', 'FIRST_DAY_OF_WEEK', 'DECIMAL_SEPARATOR',
+ 'THOUSAND_SEPARATOR', 'NUMBER_GROUPING')
+
result = {}
- for attr in dir(module):
- if attr[:2] != '__':
- result[attr] = getattr(module, attr)
+ for module in (settings, django_formats_module(), project_formats_module()):
+ if module:
+ for attr in FORMAT_SETTINGS:
+ try:
+ result[attr] = getattr(module, attr)
+ except AttributeError:
+ pass
return result
NullSource = """
@@ -870,7 +870,11 @@ 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 prefedined formats vary depending on the current locale.
For example::
@@ -885,7 +889,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
@@ -1433,7 +1437,10 @@ 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.
@@ -1450,7 +1457,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
@@ -4,20 +4,21 @@
Internationalization
====================
-Django has full support for internationalization of text in code and templates.
-Here's how it works.
+Django has full support for internationalization, including translation
+capabilities of text in code and templates, and format localization for
+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 +30,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_FORMAT_I18N = True <USE_FORMAT_I18N>` in your settings file. If
+:settings:`USE_FORMAT_I18N` is set to ``True``, then 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
==================================================
@@ -1005,3 +1012,48 @@ 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
+===================
+
+Django's formatting system is disabled by default. To enable it, it's necessay
+to set :setting:`USE_FORMAT_I18N = True <USE_FORMAT_I18N>` in your settings
+file. Note that :setting:`USE_FORMAT_I18N` requires `USE_I18N` to be ``True``.
+
+When using Django's formatting system, dates and numbers on templates will be
+displayed using the format specified for the current locale. That means, 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.
+
+Creating custom format files
+----------------------------
+
+Django provides format definitions for many locales, but sometimes you could
+want to create your own ones, 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 :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. File must be named ``formats.py``.
+
+For customazing 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 thousand separator, instead of the default for English,
+comma.
+

0 comments on commit c52ae07

Please sign in to comment.