Fixed #5495 -- Made some organization / spelling / grammar changes to docs/i18n.txt. Thanks, Axis_of_Entropy
git-svn-id: http://code.djangoproject.com/svn/django/trunk@6294 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
parent
7b172de6fa
commit
b7e90a0abd
136
docs/i18n.txt
136
docs/i18n.txt
|
@ -27,21 +27,8 @@ Essentially, Django does two things:
|
||||||
* It uses these hooks to translate Web apps for particular users according
|
* It uses these hooks to translate Web apps for particular users according
|
||||||
to their language preferences.
|
to their language preferences.
|
||||||
|
|
||||||
How to internationalize your app: in three steps
|
If you don't need internationalization in your app
|
||||||
------------------------------------------------
|
==================================================
|
||||||
|
|
||||||
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
|
|
||||||
======================================
|
|
||||||
|
|
||||||
Django's internationalization hooks are on by default, and that means there's a
|
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
|
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
|
.. _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
|
Translation strings specify "This text should be translated." These strings can
|
||||||
appear in your Python code and templates. It's your responsibility to mark
|
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/
|
.. _Django templates: ../templates_python/
|
||||||
|
|
||||||
Working with lazy translation objects
|
Working with lazy translation objects
|
||||||
=====================================
|
-------------------------------------
|
||||||
|
|
||||||
Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models
|
Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models
|
||||||
and utility functions is a common operation. When you're working with these
|
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.
|
couple of helper functions.
|
||||||
|
|
||||||
Joining strings: string_concat()
|
Joining strings: string_concat()
|
||||||
--------------------------------
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Standard Python string joins (``''.join([...])``) will not work on lists
|
Standard Python string joins (``''.join([...])``) will not work on lists
|
||||||
containing lazy translation objects. Instead, you can use
|
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).
|
rendering time).
|
||||||
|
|
||||||
The allow_lazy() decorator
|
The allow_lazy() decorator
|
||||||
--------------------------
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Django offers many utility functions (particularly in ``django.utils``) that
|
Django offers many utility functions (particularly in ``django.utils``) that
|
||||||
take a string as their first argument and do something to that string. These
|
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
|
input is a proper string, then add support for lazy translation objects at the
|
||||||
end.
|
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
|
Once you've tagged your strings for later translation, you need to write (or
|
||||||
obtain) the language translations themselves. Here's how that works.
|
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.
|
...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
|
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:
|
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/
|
.. _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
|
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
|
translations that come with Django -- you'll just need to activate translation
|
||||||
|
@ -546,7 +546,7 @@ following this algorithm:
|
||||||
Notes:
|
Notes:
|
||||||
|
|
||||||
* In each of these places, the language preference is expected to be in the
|
* 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``.
|
is ``pt-br``.
|
||||||
* If a base language is available but the sublanguage specified is not,
|
* 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``
|
Django uses the base language. For example, if a user specifies ``de-at``
|
||||||
|
@ -629,44 +629,6 @@ in ``request.LANGUAGE_CODE``.
|
||||||
.. _session: ../sessions/
|
.. _session: ../sessions/
|
||||||
.. _request object: ../request_response/#httprequest-objects
|
.. _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::
|
|
||||||
|
|
||||||
<form action="/i18n/setlang/" method="post">
|
|
||||||
<input name="next" type="hidden" value="/next/page/" />
|
|
||||||
<select name="language">
|
|
||||||
{% for lang in LANGUAGES %}
|
|
||||||
<option value="{{ lang.0 }}">{{ lang.1 }}</option>
|
|
||||||
{% endfor %}
|
|
||||||
</select>
|
|
||||||
<input type="submit" value="Go" />
|
|
||||||
</form>
|
|
||||||
|
|
||||||
Using translations in your own projects
|
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
|
connected to your explicit project and not strings that are distributed
|
||||||
independently.
|
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::
|
||||||
|
|
||||||
|
<form action="/i18n/setlang/" method="post">
|
||||||
|
<input name="next" type="hidden" value="/next/page/" />
|
||||||
|
<select name="language">
|
||||||
|
{% for lang in LANGUAGES %}
|
||||||
|
<option value="{{ lang.0 }}">{{ lang.1 }}</option>
|
||||||
|
{% endfor %}
|
||||||
|
</select>
|
||||||
|
<input type="submit" value="Go" />
|
||||||
|
</form>
|
||||||
|
|
||||||
Translations and JavaScript
|
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
|
After updating translation catalogs, just run ``compile-messages.py`` the same
|
||||||
way as you do with normal Django translation catalogs.
|
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:
|
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
|
used to differentiate between different programs that store their data
|
||||||
in a common message-file library (usually ``/usr/share/locale/``). The
|
in a common message-file library (usually ``/usr/share/locale/``). The
|
||||||
``django`` domain is used for python and template translation strings
|
``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
|
domain is only used for JavaScript translation catalogs to make sure
|
||||||
that those are as small as possible.
|
that those are as small as possible.
|
||||||
* Django doesn't use ``xgettext`` alone. It uses Python wrappers around
|
* 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.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue