Commits

garc...@bcc190cf-cafb-0310-a4f2-bffc1f526a37  committed e169623

[soc2009/i18n] Date filter allowed to use predefined formats, improved fallbacks on getting formats, and documentation added.

  • Participants
  • Parent commits 0b60d2e
  • Branches soc2009/i18n-improvements

Comments (0)

Files changed (5)

File django/template/defaultfilters.py

 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()
 
     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):
     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):

File django/utils/formats.py

     """
     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

File django/views/i18n.py

 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
 
     """
     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 = """

File docs/ref/templates/builtins.txt

 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::
 
     {{ value|date }}
 
 ...the formatting string defined in the :setting:`DATE_FORMAT` setting will be
-used.
+used, without applying any localization.
 
 .. templatefilter:: default
 
 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.
     {{ value|time }}
 
 ...the formatting string defined in the :setting:`TIME_FORMAT` setting will be
-used.
+used, without aplying any localization.
 
 .. templatefilter:: timesince
 

File docs/topics/i18n.txt

 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.
     * 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
 ==================================================
 
 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.
+