[soc2009/i18n] Date filter allowed to use predefined formats, improved 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

2 files changed, 71 insertions, 12 deletions

diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 32b5984767..ba45a6f1c4 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -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
 
diff --git a/docs/topics/i18n.txt b/docs/topics/i18n.txt
index 86c03221aa..fe8020f86d 100644
--- a/docs/topics/i18n.txt
+++ b/docs/topics/i18n.txt
@@ -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.
+