diff --git a/docs/i18n.txt b/docs/i18n.txt
index 4794b39d5b..25191e9402 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -27,21 +27,8 @@ Essentially, Django does two things:
* It uses these hooks to translate Web apps for particular users according
to their language preferences.
-How to internationalize your app: in three steps
-------------------------------------------------
-
- 1. Embed translation strings in your Python code and templates.
- 2. Get translations for those strings, in whichever languages you want to
- support.
- 3. Activate the locale middleware in your Django settings.
-
-.. admonition:: Behind the scenes
-
- Django's translation machinery uses the standard ``gettext`` module that
- comes with Python.
-
-If you don't need internationalization
-======================================
+If you don't need internationalization in your app
+==================================================
Django's internationalization hooks are on by default, and that means there's a
bit of i18n-related overhead in certain places of the framework. If you don't
@@ -55,8 +42,21 @@ from your ``TEMPLATE_CONTEXT_PROCESSORS`` setting.
.. _documentation for USE_I18N: ../settings/#use-i18n
-How to specify translation strings
-==================================
+If you do need internationalization: three steps
+================================================
+
+ 1. Embed translation strings in your Python code and templates.
+ 2. Get translations for those strings, in whichever languages you want to
+ support.
+ 3. Activate the locale middleware in your Django settings.
+
+.. admonition:: Behind the scenes
+
+ Django's translation machinery uses the standard ``gettext`` module that
+ comes with Python.
+
+1. How to specify translation strings
+=====================================
Translation strings specify "This text should be translated." These strings can
appear in your Python code and templates. It's your responsibility to mark
@@ -295,7 +295,7 @@ string, so they don't need to be aware of translations.
.. _Django templates: ../templates_python/
Working with lazy translation objects
-=====================================
+-------------------------------------
Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models
and utility functions is a common operation. When you're working with these
@@ -305,7 +305,7 @@ convert them to strings, because they should be converted as late as possible
couple of helper functions.
Joining strings: string_concat()
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Standard Python string joins (``''.join([...])``) will not work on lists
containing lazy translation objects. Instead, you can use
@@ -324,7 +324,7 @@ strings when ``result`` itself is used in a string (usually at template
rendering time).
The allow_lazy() decorator
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
Django offers many utility functions (particularly in ``django.utils``) that
take a string as their first argument and do something to that string. These
@@ -359,8 +359,8 @@ Using this decorator means you can write your function and assume that the
input is a proper string, then add support for lazy translation objects at the
end.
-How to create language files
-============================
+2. How to create language files
+===============================
Once you've tagged your strings for later translation, you need to write (or
obtain) the language translations themselves. Here's how that works.
@@ -393,7 +393,7 @@ To create or update a message file, run this command::
...where ``de`` is the language code for the message file you want to create.
The language code, in this case, is in locale format. For example, it's
-``pt_BR`` for Brazilian Portugese and ``de_AT`` for Austrian German.
+``pt_BR`` for Brazilian Portuguese and ``de_AT`` for Austrian German.
The script should be run from one of three places:
@@ -490,8 +490,8 @@ That's it. Your translations are ready for use.
.. _Submitting and maintaining translations: ../contributing/
-How Django discovers language preference
-========================================
+3. How Django discovers language preference
+===========================================
Once you've prepared your translations -- or, if you just want to use the
translations that come with Django -- you'll just need to activate translation
@@ -546,7 +546,7 @@ following this algorithm:
Notes:
* In each of these places, the language preference is expected to be in the
- standard language format, as a string. For example, Brazilian Portugese
+ standard language format, as a string. For example, Brazilian Portuguese
is ``pt-br``.
* If a base language is available but the sublanguage specified is not,
Django uses the base language. For example, if a user specifies ``de-at``
@@ -629,44 +629,6 @@ in ``request.LANGUAGE_CODE``.
.. _session: ../sessions/
.. _request object: ../request_response/#httprequest-objects
-The ``set_language`` redirect view
-==================================
-
-As a convenience, Django comes with a view, ``django.views.i18n.set_language``,
-that sets a user's language preference and redirects back to the previous page.
-
-Activate this view by adding the following line to your URLconf::
-
- (r'^i18n/', include('django.conf.urls.i18n')),
-
-(Note that this example makes the view available at ``/i18n/setlang/``.)
-
-The view expects to be called via the ``POST`` method, with a ``language``
-parameter set in request. If session support is enabled, the view
-saves the language choice in the user's session. Otherwise, it saves the
-language choice in a ``django_language`` cookie.
-
-After setting the language choice, Django redirects the user, following this
-algorithm:
-
- * Django looks for a ``next`` parameter in ``POST`` request.
- * If that doesn't exist, or is empty, Django tries the URL in the
- ``Referer`` header.
- * If that's empty -- say, if a user's browser suppresses that header --
- then the user will be redirected to ``/`` (the site root) as a fallback.
-
-Here's example HTML template code::
-
-
-
Using translations in your own projects
=======================================
@@ -728,6 +690,44 @@ The easiest way out is to store applications that are not part of the project
connected to your explicit project and not strings that are distributed
independently.
+The ``set_language`` redirect view
+==================================
+
+As a convenience, Django comes with a view, ``django.views.i18n.set_language``,
+that sets a user's language preference and redirects back to the previous page.
+
+Activate this view by adding the following line to your URLconf::
+
+ (r'^i18n/', include('django.conf.urls.i18n')),
+
+(Note that this example makes the view available at ``/i18n/setlang/``.)
+
+The view expects to be called via the ``POST`` method, with a ``language``
+parameter set in request. If session support is enabled, the view
+saves the language choice in the user's session. Otherwise, it saves the
+language choice in a ``django_language`` cookie.
+
+After setting the language choice, Django redirects the user, following this
+algorithm:
+
+ * Django looks for a ``next`` parameter in ``POST`` request.
+ * If that doesn't exist, or is empty, Django tries the URL in the
+ ``Referrer`` header.
+ * If that's empty -- say, if a user's browser suppresses that header --
+ then the user will be redirected to ``/`` (the site root) as a fallback.
+
+Here's example HTML template code::
+
+
+
Translations and JavaScript
===========================
@@ -827,13 +827,13 @@ This would create or update the translation catalog for JavaScript for German.
After updating translation catalogs, just run ``compile-messages.py`` the same
way as you do with normal Django translation catalogs.
-Specialities of Django translation
+Specialties of Django translation
==================================
-If you know ``gettext``, you might note these specialities in the way Django
+If you know ``gettext``, you might note these specialties in the way Django
does translation:
- * The string domain is ``django`` or ``djangojs``. The string domain is
+ * The string domain is ``django`` or ``djangojs``. This string domain is
used to differentiate between different programs that store their data
in a common message-file library (usually ``/usr/share/locale/``). The
``django`` domain is used for python and template translation strings
@@ -841,5 +841,5 @@ does translation:
domain is only used for JavaScript translation catalogs to make sure
that those are as small as possible.
* Django doesn't use ``xgettext`` alone. It uses Python wrappers around
- ``xgettext`` and ``msgfmt``. That's mostly for convenience.
+ ``xgettext`` and ``msgfmt``. This is mostly for convenience.