Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #17087 -- Re-organized the i18n docs to reduce confusion betwee…

…n USE_I18N/USE_L10N and the concepts of internationalization/localisation. Re

moved some duplicate content.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@17026 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 67e6e0fcf35d93f88bfb1a4cbf5c6008d99dd923 1 parent 4f00a2d
Aymeric Augustin authored October 22, 2011
121  docs/howto/i18n.txt
... ...
@@ -1,121 +0,0 @@
1  
-.. _using-translations-in-your-own-projects:
2  
-
3  
-===============================================
4  
-Using internationalization in your own projects
5  
-===============================================
6  
-
7  
-At runtime, Django builds an in-memory unified catalog of literals-translations.
8  
-To achieve this it looks for translations by following this algorithm regarding
9  
-the order in which it examines the different file paths to load the compiled
10  
-:term:`message files <message file>` (``.mo``) and the precedence of multiple
11  
-translations for the same literal:
12  
-
13  
-1. The directories listed in :setting:`LOCALE_PATHS` have the highest
14  
-   precedence, with the ones appearing first having higher precedence than
15  
-   the ones appearing later.
16  
-2. Then, it looks for and uses if it exists a ``locale`` directory in each
17  
-   of the installed apps listed in :setting:`INSTALLED_APPS`.  The ones
18  
-   appearing first have higher precedence than the ones appearing later.
19  
-3. Then, it looks for a ``locale`` directory in the project directory, or
20  
-   more accurately, in the directory containing your settings file.
21  
-4. Finally, the Django-provided base translation in ``django/conf/locale``
22  
-   is used as a fallback.
23  
-
24  
-.. deprecated:: 1.3
25  
-    Lookup in the ``locale`` subdirectory of the directory containing your
26  
-    settings file (item 3 above) is deprecated since the 1.3 release and will be
27  
-    removed in Django 1.5. You can use the :setting:`LOCALE_PATHS` setting
28  
-    instead, by listing the absolute filesystem path of such ``locale``
29  
-    directory in the setting value.
30  
-
31  
-.. seealso::
32  
-
33  
-    The translations for literals included in JavaScript assets are looked up
34  
-    following a similar but not identical algorithm. See the
35  
-    :ref:`javascript_catalog view documentation <javascript_catalog-view>` for
36  
-    more details.
37  
-
38  
-In all cases the name of the directory containing the translation is expected to
39  
-be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``,
40  
-etc.
41  
-
42  
-This way, you can write applications that include their own translations, and
43  
-you can override base translations in your project path. Or, you can just build
44  
-a big project out of several apps and put all translations into one big common
45  
-message file specific to the project you are composing. The choice is yours.
46  
-
47  
-.. note::
48  
-
49  
-    If you're using manually configured settings, as described in
50  
-    :ref:`settings-without-django-settings-module`, the ``locale`` directory in
51  
-    the project directory will not be examined, since Django loses the ability
52  
-    to work out the location of the project directory. (Django normally uses the
53  
-    location of the settings file to determine this, and a settings file doesn't
54  
-    exist if you're manually configuring your settings.)
55  
-
56  
-All message file repositories are structured the same way. They are:
57  
-
58  
-* All paths listed in :setting:`LOCALE_PATHS` in your settings file are
59  
-  searched for ``<language>/LC_MESSAGES/django.(po|mo)``
60  
-* ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)`` --
61  
-  deprecated, see above.
62  
-* ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
63  
-* ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
64  
-
65  
-To create message files, you use the :djadmin:`django-admin.py makemessages <makemessages>`
66  
-tool. You only need to be in the same directory where the ``locale/`` directory
67  
-is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>`
68  
-to produce the binary ``.mo`` files that are used by ``gettext``. Read the
69  
-:doc:`/topics/i18n/localization` document for more details.
70  
-
71  
-You can also run ``django-admin.py compilemessages --settings=path.to.settings``
72  
-to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
73  
-setting.
74  
-
75  
-Finally, you should give some thought to the structure of your translation
76  
-files. If your applications need to be delivered to other users and will
77  
-be used in other projects, you might want to use app-specific translations.
78  
-But using app-specific translations and project-specific translations could
79  
-produce weird problems with ``makemessages``: It will traverse all directories
80  
-below the current path and so might put message IDs into a unified, common
81  
-message file for the current project that are already in application message
82  
-files.
83  
-
84  
-The easiest way out is to store applications that are not part of the project
85  
-(and so carry their own translations) outside the project tree. That way,
86  
-``django-admin.py makemessages``, when ran on a project level will only extract
87  
-strings that are connected to your explicit project and not strings that are
88  
-distributed independently.
89  
-
90  
-Using translations outside views and templates
91  
-==============================================
92  
-
93  
-While Django provides a rich set of i18n tools for use in views and templates,
94  
-it does not restrict the usage to Django-specific code. The Django translation
95  
-mechanisms can be used to translate arbitrary texts to any language that is
96  
-supported by Django (as long as an appropriate translation catalog exists, of
97  
-course). You can load a translation catalog, activate it and translate text to
98  
-language of your choice, but remember to switch back to original language, as
99  
-activating a translation catalog is done on per-thread basis and such change
100  
-will affect code running in the same thread.
101  
-
102  
-For example::
103  
-
104  
-    from django.utils import translation
105  
-    def welcome_translated(language):
106  
-        cur_language = translation.get_language()
107  
-        try:
108  
-            translation.activate(language)
109  
-            text = translation.ugettext('welcome')
110  
-        finally:
111  
-            translation.activate(cur_language)
112  
-        return text
113  
-
114  
-Calling this function with the value 'de' will give you ``"Willkommen"``,
115  
-regardless of :setting:`LANGUAGE_CODE` and language set by middleware.
116  
-
117  
-Functions of particular interest are ``django.utils.translation.get_language()``
118  
-which returns the language used in the current thread,
119  
-``django.utils.translation.activate()`` which activates a translation catalog
120  
-for the current thread, and ``django.utils.translation.check_for_language()``
121  
-which checks if the given language is supported by Django.
1  docs/howto/index.txt
@@ -18,7 +18,6 @@ you quickly accomplish common tasks.
18 18
    deployment/index
19 19
    error-reporting
20 20
    initial-data
21  
-   i18n
22 21
    jython
23 22
    legacy-databases
24 23
    outputting-csv
2  docs/internals/contributing/index.txt
@@ -56,7 +56,7 @@ Browse the following sections to find out how:
56 56
    triaging-tickets
57 57
    writing-code/index
58 58
    writing-documentation
59  
-   translations
  59
+   localizing
60 60
    committing-code
61 61
 
62 62
 .. _django-users: http://groups.google.com/group/django-users
22  docs/internals/contributing/translations.txt → docs/internals/contributing/localizing.txt
... ...
@@ -1,15 +1,15 @@
1  
-=======================================
2  
-Submitting and maintaining translations
3  
-=======================================
  1
+=================
  2
+Localizing Django
  3
+=================
4 4
 
5 5
 Various parts of Django, such as the admin site and validation error messages,
6  
-are internationalized. This means they display different text depending on each
7  
-user's language setting. For this, Django uses the same internationalization and
8  
-localization infrastructure available to Django applications, described in the
9  
-:doc:`i18n documentation</topics/i18n/index>`.
  6
+are internationalized. This means they display differently depending on each
  7
+user's language or country. For this, Django uses the same internationalization
  8
+and localization infrastructure available to Django applications, described in
  9
+the :doc:`i18n documentation </topics/i18n/index>`.
10 10
 
11  
-Internationalization
12  
---------------------
  11
+Translations
  12
+------------
13 13
 
14 14
 Translations are contributed by Django users worldwide. The translation work is
15 15
 coordinated at `Transifex`_.
@@ -45,8 +45,8 @@ do:
45 45
      For more information about how to use Transifex, read the
46 46
      `Transifex User Guide`_.
47 47
 
48  
-Localization
49  
-------------
  48
+Formats
  49
+-------
50 50
 
51 51
 You can also review ``conf/locale/<locale>/formats.py``. This file describes
52 52
 the date, time and numbers formatting particularities of your locale. See
2  docs/ref/contrib/localflavor.txt
@@ -146,7 +146,7 @@ Django's general catalog in ``django/conf/locale``. If you want localflavor's
146 146
 texts to be translated, like form fields error messages, you must include
147 147
 :mod:`django.contrib.localflavor` in the :setting:`INSTALLED_APPS` setting, so
148 148
 the internationalization system can find the catalog, as explained in
149  
-:ref:`using-translations-in-your-own-projects`.
  149
+:ref:`how-django-discovers-translations`.
150 150
 
151 151
 Adding flavors
152 152
 ==============
16  docs/ref/settings.txt
@@ -1243,7 +1243,7 @@ LOCALE_PATHS
1243 1243
 Default: ``()`` (Empty tuple)
1244 1244
 
1245 1245
 A tuple of directories where Django looks for translation files.
1246  
-See :ref:`using-translations-in-your-own-projects`.
  1246
+See :ref:`how-django-discovers-translations`.
1247 1247
 
1248 1248
 Example::
1249 1249
 
@@ -2038,10 +2038,10 @@ USE_I18N
2038 2038
 
2039 2039
 Default: ``True``
2040 2040
 
2041  
-A boolean that specifies whether Django's internationalization system should be
2042  
-enabled. This provides an easy way to turn it off, for performance. If this is
2043  
-set to ``False``, Django will make some optimizations so as not to load the
2044  
-internationalization machinery.
  2041
+A boolean that specifies whether Django's translation system should be enabled.
  2042
+This provides an easy way to turn it off, for performance. If this is set to
  2043
+``False``, Django will make some optimizations so as not to load the
  2044
+translation machinery.
2045 2045
 
2046 2046
 See also :setting:`USE_L10N`
2047 2047
 
@@ -2054,9 +2054,9 @@ USE_L10N
2054 2054
 
2055 2055
 Default: ``False``
2056 2056
 
2057  
-A boolean that specifies if data will be localized by default or not. If this
2058  
-is set to ``True``, e.g. Django will display numbers and dates using the
2059  
-format of the current locale.
  2057
+A boolean that specifies if localized formatting of data will be enabled by
  2058
+default or not. If this is set to ``True``, e.g. Django will display numbers and
  2059
+dates using the format of the current locale.
2060 2060
 
2061 2061
 See also :setting:`USE_I18N` and :setting:`LANGUAGE_CODE`
2062 2062
 
2  docs/ref/utils.txt
@@ -455,7 +455,7 @@ appropriate entities.
455 455
    :synopsis: Internationalization support.
456 456
 
457 457
 For a complete discussion on the usage of the following see the
458  
-:doc:`Internationalization documentation </topics/i18n/internationalization>`.
  458
+:doc:`translation documentation </topics/i18n/translation>`.
459 459
 
460 460
 .. function:: gettext(message)
461 461
 
9  docs/topics/cache.txt
@@ -494,12 +494,9 @@ more on these decorators.
494 494
 .. versionadded:: 1.2
495 495
 
496 496
 If :setting:`USE_I18N` is set to ``True`` then the generated cache key will
497  
-include the name of the active :term:`language<language code>`.
498  
-This allows you to easily cache multilingual sites without having to create
499  
-the cache key yourself.
500  
-
501  
-See :doc:`/topics/i18n/deployment` for more on how Django discovers the active
502  
-language.
  497
+include the name of the active :term:`language<language code>` -- see also
  498
+:ref:`how-django-discovers-language-preference`). This allows you to easily
  499
+cache multilingual sites without having to create the cache key yourself.
503 500
 
504 501
 __ `Controlling cache: Using other headers`_
505 502
 
217  docs/topics/i18n/deployment.txt
... ...
@@ -1,217 +0,0 @@
1  
-==========================
2  
-Deployment of translations
3  
-==========================
4  
-
5  
-If you don't need internationalization
6  
-======================================
7  
-
8  
-Django's internationalization hooks are on by default, and that means there's a
9  
-bit of i18n-related overhead in certain places of the framework. If you don't
10  
-use internationalization, you should take the two seconds to set
11  
-:setting:`USE_I18N = False <USE_I18N>` in your settings file. If
12  
-:setting:`USE_I18N` is set to ``False``, then Django will make some
13  
-optimizations so as not to load the internationalization machinery.
14  
-
15  
-You'll probably also want to remove ``'django.core.context_processors.i18n'``
16  
-from your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
17  
-
18  
-.. note::
19  
-
20  
-    There is also an independent but related :setting:`USE_L10N` setting that
21  
-    controls if Django should implement format localization.
22  
-
23  
-    If :setting:`USE_L10N` is set to ``True``, Django will handle numbers times,
24  
-    and dates in the format of the current locale. That includes representation
25  
-    of these field types on templates and allowed input formats for dates,
26  
-    times on model forms.
27  
-
28  
-    See :ref:`format-localization` for more details.
29  
-
30  
-If you do need internationalization
31  
-===================================
32  
-
33  
-.. _how-django-discovers-language-preference:
34  
-
35  
-How Django discovers language preference
36  
-----------------------------------------
37  
-
38  
-Once you've prepared your translations -- or, if you just want to use the
39  
-translations that come with Django -- you'll just need to activate translation
40  
-for your app.
41  
-
42  
-Behind the scenes, Django has a very flexible model of deciding which language
43  
-should be used -- installation-wide, for a particular user, or both.
44  
-
45  
-To set an installation-wide language preference, set :setting:`LANGUAGE_CODE`.
46  
-Django uses this language as the default translation -- the final attempt if no
47  
-other translator finds a translation.
48  
-
49  
-If all you want to do is run Django with your native language, and a language
50  
-file is available for it, all you need to do is set :setting:`LANGUAGE_CODE`.
51  
-
52  
-If you want to let each individual user specify which language he or she
53  
-prefers, use ``LocaleMiddleware``. ``LocaleMiddleware`` enables language
54  
-selection based on data from the request. It customizes content for each user.
55  
-
56  
-To use ``LocaleMiddleware``, add ``'django.middleware.locale.LocaleMiddleware'``
57  
-to your :setting:`MIDDLEWARE_CLASSES` setting. Because middleware order
58  
-matters, you should follow these guidelines:
59  
-
60  
-* Make sure it's one of the first middlewares installed.
61  
-* It should come after ``SessionMiddleware``, because ``LocaleMiddleware``
62  
-  makes use of session data. And it should come before ``CommonMiddleware``
63  
-  because ``CommonMiddleware`` needs an activated language in order
64  
-  to resolve the requested URL.
65  
-* If you use ``CacheMiddleware``, put ``LocaleMiddleware`` after it.
66  
-
67  
-For example, your :setting:`MIDDLEWARE_CLASSES` might look like this::
68  
-
69  
-    MIDDLEWARE_CLASSES = (
70  
-       'django.contrib.sessions.middleware.SessionMiddleware',
71  
-       'django.middleware.locale.LocaleMiddleware',
72  
-       'django.middleware.common.CommonMiddleware',
73  
-    )
74  
-
75  
-(For more on middleware, see the :doc:`middleware documentation
76  
-</topics/http/middleware>`.)
77  
-
78  
-``LocaleMiddleware`` tries to determine the user's language preference by
79  
-following this algorithm:
80  
-
81  
-.. versionchanged:: 1.4
82  
-
83  
-* First, it looks for the language prefix in the requested URL.  This is
84  
-  only performed when you are using the ``i18n_patterns`` function in your
85  
-  root URLconf. See :ref:`url-internationalization` for more information
86  
-  about the language prefix and how to internationalize URL patterns.
87  
-
88  
-* Failing that, it looks for a ``django_language`` key in the current
89  
-  user's session.
90  
-
91  
-* Failing that, it looks for a cookie.
92  
-
93  
-  The name of the cookie used is set by the :setting:`LANGUAGE_COOKIE_NAME`
94  
-  setting. (The default name is ``django_language``.)
95  
-
96  
-* Failing that, it looks at the ``Accept-Language`` HTTP header. This
97  
-  header is sent by your browser and tells the server which language(s) you
98  
-  prefer, in order by priority. Django tries each language in the header
99  
-  until it finds one with available translations.
100  
-
101  
-* Failing that, it uses the global :setting:`LANGUAGE_CODE` setting.
102  
-
103  
-.. _locale-middleware-notes:
104  
-
105  
-Notes:
106  
-
107  
-* In each of these places, the language preference is expected to be in the
108  
-  standard :term:`language format<language code>`, as a string. For example,
109  
-  Brazilian Portuguese is ``pt-br``.
110  
-
111  
-* If a base language is available but the sublanguage specified is not,
112  
-  Django uses the base language. For example, if a user specifies ``de-at``
113  
-  (Austrian German) but Django only has ``de`` available, Django uses
114  
-  ``de``.
115  
-
116  
-* Only languages listed in the :setting:`LANGUAGES` setting can be selected.
117  
-  If you want to restrict the language selection to a subset of provided
118  
-  languages (because your application doesn't provide all those languages),
119  
-  set :setting:`LANGUAGES` to a list of languages. For example::
120  
-
121  
-      LANGUAGES = (
122  
-        ('de', _('German')),
123  
-        ('en', _('English')),
124  
-      )
125  
-
126  
-  This example restricts languages that are available for automatic
127  
-  selection to German and English (and any sublanguage, like de-ch or
128  
-  en-us).
129  
-
130  
-* If you define a custom :setting:`LANGUAGES` setting, as explained in the
131  
-  previous bullet, it's OK to mark the languages as translation strings
132  
-  -- but use a "dummy" ``ugettext()`` function, not the one in
133  
-  ``django.utils.translation``. You should *never* import
134  
-  ``django.utils.translation`` from within your settings file, because that
135  
-  module in itself depends on the settings, and that would cause a circular
136  
-  import.
137  
-
138  
-  The solution is to use a "dummy" ``ugettext()`` function. Here's a sample
139  
-  settings file::
140  
-
141  
-      ugettext = lambda s: s
142  
-
143  
-      LANGUAGES = (
144  
-          ('de', ugettext('German')),
145  
-          ('en', ugettext('English')),
146  
-      )
147  
-
148  
-  With this arrangement, ``django-admin.py makemessages`` will still find
149  
-  and mark these strings for translation, but the translation won't happen
150  
-  at runtime -- so you'll have to remember to wrap the languages in the
151  
-  *real* ``ugettext()`` in any code that uses :setting:`LANGUAGES` at
152  
-  runtime.
153  
-
154  
-* The ``LocaleMiddleware`` can only select languages for which there is a
155  
-  Django-provided base translation. If you want to provide translations
156  
-  for your application that aren't already in the set of translations
157  
-  in Django's source tree, you'll want to provide at least a basic
158  
-  one as described in the :ref:`Locale restrictions<locale-restrictions>`
159  
-  note.
160  
-
161  
-Once ``LocaleMiddleware`` determines the user's preference, it makes this
162  
-preference available as ``request.LANGUAGE_CODE`` for each
163  
-:class:`~django.http.HttpRequest`. Feel free to read this value in your view
164  
-code. Here's a simple example::
165  
-
166  
-    def hello_world(request, count):
167  
-        if request.LANGUAGE_CODE == 'de-at':
168  
-            return HttpResponse("You prefer to read Austrian German.")
169  
-        else:
170  
-            return HttpResponse("You prefer to read another language.")
171  
-
172  
-Note that, with static (middleware-less) translation, the language is in
173  
-``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's
174  
-in ``request.LANGUAGE_CODE``.
175  
-
176  
-.. _settings file: ../settings/
177  
-.. _middleware documentation: ../middleware/
178  
-.. _session: ../sessions/
179  
-.. _request object: ../request_response/#httprequest-objects
180  
-
181  
-How Django discovers translations
182  
----------------------------------
183  
-
184  
-As described in :ref:`using-translations-in-your-own-projects`, Django looks for
185  
-translations by following this algorithm regarding the order in which it
186  
-examines the different file paths to load the compiled :term:`message files
187  
-<message file>` (``.mo``) and the precedence of multiple translations for the
188  
-same literal:
189  
-
190  
-1. The directories listed in :setting:`LOCALE_PATHS` have the highest
191  
-   precedence, with the ones appearing first having higher precedence than
192  
-   the ones appearing later.
193  
-2. Then, it looks for and uses if it exists a ``locale`` directory in each
194  
-   of the installed apps listed in :setting:`INSTALLED_APPS`.  The ones
195  
-   appearing first have higher precedence than the ones appearing later.
196  
-3. Then, it looks for a ``locale`` directory in the project directory, or
197  
-   more accurately, in the directory containing your settings file.
198  
-4. Finally, the Django-provided base translation in ``django/conf/locale``
199  
-   is used as a fallback.
200  
-
201  
-.. deprecated:: 1.3
202  
-    Lookup in the ``locale`` subdirectory of the directory containing your
203  
-    settings file (item 3 above) is deprecated since the 1.3 release and will be
204  
-    removed in Django 1.5. You can use the :setting:`LOCALE_PATHS` setting
205  
-    instead, by listing the absolute filesystem path of such ``locale``
206  
-    directory in the setting value.
207  
-
208  
-.. seealso::
209  
-
210  
-    The translations for literals included in JavaScript assets are looked up
211  
-    following a similar but not identical algorithm. See the
212  
-    :ref:`javascript_catalog view documentation <javascript_catalog-view>` for
213  
-    more details.
214  
-
215  
-In all cases the name of the directory containing the translation is expected to
216  
-be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``,
217  
-etc.
182  docs/topics/i18n/formatting.txt
... ...
@@ -0,0 +1,182 @@
  1
+===================
  2
+Format localization
  3
+===================
  4
+
  5
+.. _format-localization:
  6
+
  7
+.. versionadded:: 1.2
  8
+
  9
+Overview
  10
+========
  11
+
  12
+Django's formatting system is capable to display dates, times and numbers in templates using the format specified for the current :term:`locale <locale
  13
+name>`. It also handles localized input in forms.
  14
+
  15
+When it's enabled, two users accessing the same content may see dates, times and
  16
+numbers formatted in different ways, depending on the formats for their current
  17
+locale.
  18
+
  19
+The formatting system is disabled by default. To enable it, it's
  20
+necessary to set :setting:`USE_L10N = True <USE_L10N>` in your settings file.
  21
+
  22
+.. note::
  23
+
  24
+    The default :file:`settings.py` file created by :djadmin:`django-admin.py
  25
+    startproject <startproject>` includes :setting:`USE_L10N = True <USE_L10N>`
  26
+    for convenience.
  27
+
  28
+.. note::
  29
+
  30
+    There is also an independent but related :setting:`USE_I18N` setting that
  31
+    controls if Django should activate translation. See
  32
+    :doc:`/topics/i18n/translation` for more details.
  33
+
  34
+Locale aware input in forms
  35
+===========================
  36
+
  37
+When formatting is enabled, Django can use localized formats when parsing dates,
  38
+times and numbers in forms. That means it tries different formats for different
  39
+locales when guessing the format used by the user when inputting data on forms.
  40
+
  41
+.. note::
  42
+    Django uses different formats for displaying data to those it uses for
  43
+    parsing data. Most notably, the formats for parsing dates can't use the
  44
+    ``%a`` (abbreviated weekday name), ``%A`` (full weekday name),
  45
+    ``%b`` (abbreviated month name), ``%B`` (full month name),
  46
+    or ``%p`` (AM/PM).
  47
+
  48
+To enable a form field to localize input and output data simply use its
  49
+``localize`` argument::
  50
+
  51
+    class CashRegisterForm(forms.Form):
  52
+       product = forms.CharField()
  53
+       revenue = forms.DecimalField(max_digits=4, decimal_places=2, localize=True)
  54
+
  55
+.. _topic-l10n-templates:
  56
+
  57
+Controlling localization in templates
  58
+=====================================
  59
+
  60
+When you have enabled formatting with :setting:`USE_L10N`, Django
  61
+will try to use a locale specific format whenever it outputs a value
  62
+in a template.
  63
+
  64
+However, it may not always be appropriate to use localized values --
  65
+for example, if you're outputting Javascript or XML that is designed
  66
+to be machine-readable, you will always want unlocalized values. You
  67
+may also want to use localization in selected templates, rather than
  68
+using localization everywhere.
  69
+
  70
+To allow for fine control over the use of localization, Django
  71
+provides the ``l10n`` template library that contains the following
  72
+tags and filters.
  73
+
  74
+Template tags
  75
+-------------
  76
+
  77
+.. templatetag:: localize
  78
+
  79
+localize
  80
+~~~~~~~~
  81
+
  82
+.. versionadded:: 1.3
  83
+
  84
+Enables or disables localization of template variables in the
  85
+contained block.
  86
+
  87
+This tag allows a more fine grained control of localization than
  88
+:setting:`USE_L10N`.
  89
+
  90
+To activate or deactivate localization for a template block, use::
  91
+
  92
+    {% load l10n %}
  93
+
  94
+    {% localize on %}
  95
+        {{ value }}
  96
+    {% endlocalize %}
  97
+
  98
+    {% localize off %}
  99
+        {{ value }}
  100
+    {% endlocalize %}
  101
+
  102
+.. note::
  103
+
  104
+    The value of :setting:`USE_L10N` isn't respected inside of a
  105
+    ``{% localize %}`` block.
  106
+
  107
+See :tfilter:`localize` and :tfilter:`unlocalize` for template filters that will
  108
+do the same job on a per-variable basis.
  109
+
  110
+Template filters
  111
+----------------
  112
+
  113
+.. templatefilter:: localize
  114
+
  115
+localize
  116
+~~~~~~~~
  117
+
  118
+.. versionadded:: 1.3
  119
+
  120
+Forces localization of a single value.
  121
+
  122
+For example::
  123
+
  124
+    {% load l10n %}
  125
+
  126
+    {{ value|localize }}
  127
+
  128
+To disable localization on a single value, use :tfilter:`unlocalize`. To control
  129
+localization over a large section of a template, use the :ttag:`localize` template
  130
+tag.
  131
+
  132
+
  133
+.. templatefilter:: unlocalize
  134
+
  135
+unlocalize
  136
+~~~~~~~~~~
  137
+
  138
+.. versionadded:: 1.3
  139
+
  140
+Forces a single value to be printed without localization.
  141
+
  142
+For example::
  143
+
  144
+    {% load l10n %}
  145
+
  146
+    {{ value|unlocalize }}
  147
+
  148
+To force localization of a single value, use :tfilter:`localize`. To
  149
+control localization over a large section of a template, use the
  150
+:ttag:`localize` template tag.
  151
+
  152
+Creating custom format files
  153
+============================
  154
+
  155
+Django provides format definitions for many locales, but sometimes you might
  156
+want to create your own, because a format files doesn't exist for your locale,
  157
+or because you want to overwrite some of the values.
  158
+
  159
+To use custom formats, specify the path where you'll place format files first.
  160
+To do that, just set your :setting:`FORMAT_MODULE_PATH` setting to the package
  161
+where format files will exist, for instance::
  162
+
  163
+    FORMAT_MODULE_PATH = 'mysite.formats'
  164
+
  165
+Files are not placed directly in this directory, but in a directory named as
  166
+the locale, and must be named ``formats.py``.
  167
+
  168
+To customize the English formats, a structure like this would be needed::
  169
+
  170
+    mysite/
  171
+        formats/
  172
+            __init__.py
  173
+            en/
  174
+                __init__.py
  175
+                formats.py
  176
+
  177
+where :file:`formats.py` contains custom format definitions. For example::
  178
+
  179
+    THOUSAND_SEPARATOR = ' '
  180
+
  181
+to use a space as a thousand separator, instead of the default for English,
  182
+a comma.
96  docs/topics/i18n/index.txt
@@ -2,64 +2,77 @@
2 2
 Internationalization and localization
3 3
 =====================================
4 4
 
  5
+.. toctree::
  6
+   :hidden:
  7
+   :maxdepth: 1
  8
+
  9
+   translation
  10
+   formatting
  11
+
5 12
 Overview
6 13
 ========
7 14
 
8  
-Django has full support for internationalization of text in code and
9  
-templates, and format localization of dates and numbers. Here's how it works.
  15
+The goal of internationalization and localization is to allow a single Web
  16
+application to offer its content in languages and formats tailored to the
  17
+audience.
  18
+
  19
+Django has full support for :doc:`translation of text
  20
+</topics/i18n/translation>` and :doc:`formatting of dates, times and numbers
  21
+</topics/i18n/formatting>`.
10 22
 
11 23
 Essentially, Django does two things:
12 24
 
13  
-* It allows developers and template authors to specify which parts of
14  
-  their apps should be translatable.
15  
-* It uses these hooks to translate Web apps for particular users according
16  
-  to their language preferences.
  25
+* It allows developers and template authors to specify which parts of their apps
  26
+  should be translated or formatted for local languages and cultures.
  27
+* It uses these hooks to localize Web apps for particular users according to
  28
+  their preferences.
17 29
 
18  
-The complete process can be seen as divided in three stages. It is also possible
19  
-to identify an identical number of roles with very well defined responsibilities
20  
-associated with each of these tasks (although it's perfectly normal if you
21  
-find yourself performing more than one of these roles):
  30
+Obviously, translation depends on the target language. Formatting usually
  31
+depends on the target country.
22 32
 
23  
-* For application authors wishing to make sure their Django apps can be
24  
-  used in different locales: :doc:`/topics/i18n/internationalization`.
25  
-* For translators wanting to translate Django apps: :doc:`/topics/i18n/localization`.
26  
-* For system administrators/final users setting up internationalized apps or
27  
-  developers integrating third party apps: :doc:`/topics/i18n/deployment`.
  33
+Definitions
  34
+===========
28 35
 
29  
-.. toctree::
30  
-   :hidden:
31  
-   :maxdepth: 1
  36
+The words "internationalization" and "localization" often cause confusion;
  37
+here's a simplified definition:
  38
+
  39
+.. glossary::
32 40
 
33  
-   internationalization
34  
-   localization
35  
-   deployment
  41
+    internationalization
  42
+      Preparing the software for localization. Usually done by developers.
36 43
 
37  
-.. _ seealso::
  44
+    localization
  45
+      Writing the translations and local formats. Usually done by translators.
38 46
 
39  
-For more general information about the topic, see the `GNU gettext documentation`_
40  
-and the `Wikipedia article`_.
  47
+More details can be found in the `W3C Web Internationalization FAQ`_, the `Wikipedia article`_ or the `GNU gettext documentation`_.
41 48
 
  49
+.. _W3C Web Internationalization FAQ: http://www.w3.org/International/questions/qa-i18n
42 50
 .. _GNU gettext documentation: http://www.gnu.org/software/gettext/manual/gettext.html#Concepts
43 51
 .. _Wikipedia article: http://en.wikipedia.org/wiki/Internationalization_and_localization
44 52
 
45  
-Glossary
46  
-========
  53
+.. warning::
47 54
 
48  
-First lets define some terms that will help us to handle a common language:
  55
+    Translation and formatting are controlled by :setting:`USE_I18N` and
  56
+    :setting:`USE_L10N` settings respectively. However, both features involve
  57
+    internationalization and localization. The names of the settings are an
  58
+    unfortunate result of Django's history.
  59
+
  60
+Here are some other terms that will help us to handle a common language:
49 61
 
50 62
 .. glossary::
51 63
 
52 64
     locale name
53 65
       A locale name, either a language specification of the form ``ll`` or a
54 66
       combined language and country specification of the form ``ll_CC``.
55  
-      Examples: ``it``, ``de_AT``, ``es``, ``pt_BR``. Note the underscore in
56  
-      some of them and the case of the part located to its right.
  67
+      Examples: ``it``, ``de_AT``, ``es``, ``pt_BR``. The language part is
  68
+      always is lower case and the country part in upper case. The separator
  69
+      is an underscore.
57 70
 
58 71
     language code
59 72
       Represents the name of a language. Browsers send the names of the
60 73
       languages they accept in the ``Accept-Language`` HTTP header using this
61  
-      format. Examples: ``it``, ``de-at``, ``es``, ``pt-br``. Note the ``-``
62  
-      separator.
  74
+      format. Examples: ``it``, ``de-at``, ``es``, ``pt-br``. Both the language
  75
+      and the country parts are in lower case. The separator is a dash.
63 76
 
64 77
     message file
65 78
       A message file is a plain-text file, representing a single language,
@@ -70,21 +83,6 @@ First lets define some terms that will help us to handle a common language:
70 83
     translation string
71 84
       A literal that can be translated.
72 85
 
73  
-.. _specialties-of-django-i18n:
74  
-
75  
-Specialties of Django translation
76  
-=================================
77  
-
78  
-Django's translation machinery uses the standard ``gettext`` module that comes
79  
-with Python. If you know ``gettext``, you might note these specialties in the
80  
-way Django does translation:
81  
-
82  
-* The string domain is ``django`` or ``djangojs``. This string domain is
83  
-  used to differentiate between different programs that store their data
84  
-  in a common message-file library (usually ``/usr/share/locale/``). The
85  
-  ``django`` domain is used for python and template translation strings
86  
-  and is loaded into the global translation catalogs. The ``djangojs``
87  
-  domain is only used for JavaScript translation catalogs to make sure
88  
-  that those are as small as possible.
89  
-* Django doesn't use ``xgettext`` alone. It uses Python wrappers around
90  
-  ``xgettext`` and ``msgfmt``. This is mostly for convenience.
  86
+    format file
  87
+      A format file is a Python module that defines the data formats for a given
  88
+      locale.
409  docs/topics/i18n/localization.txt
... ...
@@ -1,409 +0,0 @@
1  
-============
2  
-Localization
3  
-============
4  
-
5  
-This document covers three localization-related topics: `Creating language
6  
-files`_ , `locale aware date, time and numbers input/output in forms`_,
7  
-and `controlling localization in templates`_.
8  
-
9  
-.. _`Creating language files`: how-to-create-language-files_
10  
-.. _`locale aware date, time and numbers input/output in forms`: format-localization_
11  
-.. _`controlling localization in templates`: topic-l10n-templates_
12  
-
13  
-.. seealso::
14  
-
15  
-    The :doc:`/howto/i18n` document included with the Django HOW-TO documents collection.
16  
-
17  
-.. _how-to-create-language-files:
18  
-
19  
-How to create language files
20  
-============================
21  
-
22  
-Once the string literals of an application have been tagged for later
23  
-translation, the translation themselves need to be written (or obtained). Here's
24  
-how that works.
25  
-
26  
-.. _locale-restrictions:
27  
-
28  
-.. admonition:: Locale restrictions
29  
-
30  
-    Django does not support localizing your application into a locale for which
31  
-    Django itself has not been translated. In this case, it will ignore your
32  
-    translation files. If you were to try this and Django supported it, you
33  
-    would inevitably see a mixture of translated strings (from your application)
34  
-    and English strings (from Django itself). If you want to support a locale
35  
-    for your application that is not already part of Django, you'll need to make
36  
-    at least a minimal translation of the Django core.
37  
-
38  
-    A good starting point is to copy the Django English ``.po`` file and to
39  
-    translate at least some :term:`translation strings <translation string>`.
40  
-
41  
-Message files
42  
--------------
43  
-
44  
-The first step is to create a :term:`message file` for a new language. A message
45  
-file is a plain-text file, representing a single language, that contains all
46  
-available translation strings and how they should be represented in the given
47  
-language. Message files have a ``.po`` file extension.
48  
-
49  
-Django comes with a tool, ``django-admin.py makemessages``, that automates the
50  
-creation and upkeep of these files.
51  
-
52  
-.. admonition:: Gettext utilities
53  
-
54  
-    The ``makemessages`` command (and ``compilemessages`` discussed later) use
55  
-    commands from the GNU gettext toolset: ``xgettext``, ``msgfmt``,
56  
-    ``msgmerge`` and ``msguniq``.
57  
-
58  
-    .. versionchanged:: 1.2
59  
-
60  
-    The minimum version of the ``gettext`` utilities supported is 0.15.
61  
-
62  
-To create or update a message file, run this command::
63  
-
64  
-    django-admin.py makemessages -l de
65  
-
66  
-...where ``de`` is the language code for the message file you want to create.
67  
-The language code, in this case, is in :term:`locale format<locale name>`. For
68  
-example, it's ``pt_BR`` for Brazilian Portuguese and ``de_AT`` for Austrian
69  
-German.
70  
-
71  
-The script should be run from one of two places:
72  
-
73  
-* The root directory of your Django project.
74  
-* The root directory of your Django app.
75  
-
76  
-The script runs over your project source tree or your application source tree
77  
-and pulls out all strings marked for translation. It creates (or updates) a
78  
-message file in the directory ``locale/LANG/LC_MESSAGES``. In the ``de``
79  
-example, the file will be ``locale/de/LC_MESSAGES/django.po``.
80  
-
81  
-By default ``django-admin.py makemessages`` examines every file that has the
82  
-``.html`` or ``.txt`` file extension. In case you want to override that
83  
-default, use the ``--extension`` or ``-e`` option to specify the file
84  
-extensions to examine::
85  
-
86  
-    django-admin.py makemessages -l de -e txt
87  
-
88  
-Separate multiple extensions with commas and/or use ``-e`` or ``--extension``
89  
-multiple times::
90  
-
91  
-    django-admin.py makemessages -l de -e html,txt -e xml
92  
-
93  
-When :ref:`creating message files from JavaScript source code
94  
-<creating-message-files-from-js-code>` you need to use the special 'djangojs'
95  
-domain, **not** ``-e js``.
96  
-
97  
-.. admonition:: No gettext?
98  
-
99  
-    If you don't have the ``gettext`` utilities installed, ``django-admin.py
100  
-    makemessages`` will create empty files. If that's the case, either install
101  
-    the ``gettext`` utilities or just copy the English message file
102  
-    (``locale/en/LC_MESSAGES/django.po``) if available and use it as a starting
103  
-    point; it's just an empty translation file.
104  
-
105  
-.. admonition:: Working on Windows?
106  
-
107  
-   If you're using Windows and need to install the GNU gettext utilities so
108  
-   ``django-admin makemessages`` works see :ref:`gettext_on_windows` for more
109  
-   information.
110  
-
111  
-The format of ``.po`` files is straightforward. Each ``.po`` file contains a
112  
-small bit of metadata, such as the translation maintainer's contact
113  
-information, but the bulk of the file is a list of **messages** -- simple
114  
-mappings between translation strings and the actual translated text for the
115  
-particular language.
116  
-
117  
-For example, if your Django app contained a translation string for the text
118  
-``"Welcome to my site."``, like so::
119  
-
120  
-    _("Welcome to my site.")
121  
-
122  
-...then ``django-admin.py makemessages`` will have created a ``.po`` file
123  
-containing the following snippet -- a message::
124  
-
125  
-    #: path/to/python/module.py:23
126  
-    msgid "Welcome to my site."
127  
-    msgstr ""
128  
-
129  
-A quick explanation:
130  
-
131  
-* ``msgid`` is the translation string, which appears in the source. Don't
132  
-  change it.
133  
-* ``msgstr`` is where you put the language-specific translation. It starts
134  
-  out empty, so it's your responsibility to change it. Make sure you keep
135  
-  the quotes around your translation.
136  
-* As a convenience, each message includes, in the form of a comment line
137  
-  prefixed with ``#`` and located above the ``msgid`` line, the filename and
138  
-  line number from which the translation string was gleaned.
139  
-
140  
-Long messages are a special case. There, the first string directly after the
141  
-``msgstr`` (or ``msgid``) is an empty string. Then the content itself will be
142  
-written over the next few lines as one string per line. Those strings are
143  
-directly concatenated. Don't forget trailing spaces within the strings;
144  
-otherwise, they'll be tacked together without whitespace!
145  
-
146  
-.. admonition:: Mind your charset
147  
-
148  
-    When creating a PO file with your favorite text editor, first edit
149  
-    the charset line (search for ``"CHARSET"``) and set it to the charset
150  
-    you'll be using to edit the content. Due to the way the ``gettext`` tools
151  
-    work internally and because we want to allow non-ASCII source strings in
152  
-    Django's core and your applications, you **must** use UTF-8 as the encoding
153  
-    for your PO file. This means that everybody will be using the same
154  
-    encoding, which is important when Django processes the PO files.
155  
-
156  
-To reexamine all source code and templates for new translation strings and
157  
-update all message files for **all** languages, run this::
158  
-
159  
-    django-admin.py makemessages -a
160  
-
161  
-Compiling message files
162  
------------------------
163  
-
164  
-After you create your message file -- and each time you make changes to it --
165  
-you'll need to compile it into a more efficient form, for use by ``gettext``.
166  
-Do this with the ``django-admin.py compilemessages`` utility.
167  
-
168  
-This tool runs over all available ``.po`` files and creates ``.mo`` files, which
169  
-are binary files optimized for use by ``gettext``. In the same directory from
170  
-which you ran ``django-admin.py makemessages``, run ``django-admin.py
171  
-compilemessages`` like this::
172  
-
173  
-   django-admin.py compilemessages
174  
-
175  
-That's it. Your translations are ready for use.
176  
-
177  
-.. admonition:: Working on Windows?
178  
-
179  
-   If you're using Windows and need to install the GNU gettext utilities so
180  
-   ``django-admin compilemessages`` works see :ref:`gettext_on_windows` for more
181  
-   information.
182  
-
183  
-.. admonition:: .po files: Encoding and BOM usage.
184  
-
185  
-   Django only supports ``.po`` files encoded in UTF-8 and without any BOM
186  
-   (Byte Order Mark) so if your text editor adds such marks to the beginning of
187  
-   files by default then you will need to reconfigure it.
188  
-
189  
-.. _creating-message-files-from-js-code:
190  
-
191  
-Creating message files from JavaScript source code
192  
-==================================================
193  
-
194  
-You create and update the message files the same way as the other Django
195  
-message files -- with the ``django-admin.py makemessages`` tool. The only
196  
-difference is you need to explicitly specify what in gettext parlance is known
197  
-as a domain in this case the ``djangojs`` domain, by providing a ``-d djangojs``
198  
-parameter, like this::
199  
-
200  
-    django-admin.py makemessages -d djangojs -l de
201  
-
202  
-This would create or update the message file for JavaScript for German.
203  
-After updating message files, just run ``django-admin.py compilemessages``
204  
-the same way as you do with normal Django message files.
205  
-
206  
-.. _gettext_on_windows:
207  
-
208  
-``gettext`` on Windows
209  
-======================
210  
-
211  
-This is only needed for people who either want to extract message IDs or compile
212  
-message files (``.po``). Translation work itself just involves editing existing
213  
-files of this type, but if you want to create your own message files, or want to
214  
-test or compile a changed message file, you will need the ``gettext`` utilities:
215  
-
216  
-* Download the following zip files from the GNOME servers
217  
-  http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/ or from one
218  
-  of its mirrors_
219  
-
220  
-  * ``gettext-runtime-X.zip``
221  
-  * ``gettext-tools-X.zip``
222  
-
223  
-  ``X`` is the version number, we are requiring ``0.15`` or higher.
224  
-
225  
-* Extract the contents of the ``bin\`` directories in both files to the
226  
-  same folder on your system (i.e. ``C:\Program Files\gettext-utils``)
227  
-
228  
-* Update the system PATH:
229  
-
230  
-  * ``Control Panel > System > Advanced > Environment Variables``.
231  
-  * In the ``System variables`` list, click ``Path``, click ``Edit``.
232  
-  * Add ``;C:\Program Files\gettext-utils\bin`` at the end of the
233  
-    ``Variable value`` field.
234  
-
235  
-.. _mirrors: http://ftp.gnome.org/pub/GNOME/MIRRORS
236  
-
237  
-You may also use ``gettext`` binaries you have obtained elsewhere, so long as
238  
-the ``xgettext --version`` command works properly. Do not attempt to use Django
239  
-translation utilities with a ``gettext`` package if the command ``xgettext
240  
---version`` entered at a Windows command prompt causes a popup window saying
241  
-"xgettext.exe has generated errors and will be closed by Windows".
242  
-
243  
-.. _format-localization:
244  
-
245  
-Format localization
246  
-===================
247  
-
248  
-.. versionadded:: 1.2
249  
-
250  
-Django's formatting system is disabled by default. To enable it, it's
251  
-necessary to set :setting:`USE_L10N = True <USE_L10N>` in your settings file.
252  
-
253  
-.. note::
254  
-
255  
-    The default :file:`settings.py` file created by :djadmin:`django-admin.py
256  
-    startproject <startproject>` includes :setting:`USE_L10N = True <USE_L10N>`
257  
-    for convenience.
258  
-
259  
-When using Django's formatting system, dates and numbers on templates will be
260  
-displayed using the format specified for the current locale. Two users
261  
-accessing the same content, but in different language, will see date and
262  
-number fields formatted in different ways, depending on the format for their
263  
-current locale.
264  
-
265  
-Django will also use localized formats when parsing data in forms. That means
266  
-Django uses different formats for different locales when guessing the format
267  
-used by the user when inputting data on forms.
268  
-
269  
-.. note::
270  
-    Django uses different formats for displaying data to those it uses for
271  
-    parsing data. Most notably, the formats for parsing dates can't use the
272  
-    ``%a`` (abbreviated weekday name), ``%A`` (full weekday name),
273  
-    ``%b`` (abbreviated month name), ``%B`` (full month name),
274  
-    or ``%p`` (AM/PM).
275  
-
276  
-To enable a form field to localize input and output data simply use its
277  
-``localize`` argument::
278  
-
279  
-    class CashRegisterForm(forms.Form):
280  
-       product = forms.CharField()
281  
-       revenue = forms.DecimalField(max_digits=4, decimal_places=2, localize=True)
282  
-
283  
-Creating custom format files
284  
-----------------------------
285  
-
286  
-Django provides format definitions for many locales, but sometimes you might
287  
-want to create your own, because a format files doesn't exist for your locale,
288  
-or because you want to overwrite some of the values.
289  
-
290  
-To use custom formats, first thing to do, is to specify the path where you'll
291  
-place format files. To do that, just set your :setting:`FORMAT_MODULE_PATH`
292  
-setting to the path (in the format ``'foo.bar.baz``) where format files
293  
-will exists.
294  
-
295  
-Files are not placed directly in this directory, but in a directory named as