Browse files

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: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 4f00a2d commit 67e6e0fcf35d93f88bfb1a4cbf5c6008d99dd923 @aaugustin aaugustin committed Oct 22, 2011
@@ -1,121 +0,0 @@
-.. _using-translations-in-your-own-projects:
-Using internationalization in your own projects
-At runtime, Django builds an in-memory unified catalog of literals-translations.
-To achieve this it looks for translations by following this algorithm regarding
-the order in which it examines the different file paths to load the compiled
-:term:`message files <message file>` (``.mo``) and the precedence of multiple
-translations for the same literal:
-1. The directories listed in :setting:`LOCALE_PATHS` have the highest
- precedence, with the ones appearing first having higher precedence than
- the ones appearing later.
-2. Then, it looks for and uses if it exists a ``locale`` directory in each
- of the installed apps listed in :setting:`INSTALLED_APPS`. The ones
- appearing first have higher precedence than the ones appearing later.
-3. Then, it looks for a ``locale`` directory in the project directory, or
- more accurately, in the directory containing your settings file.
-4. Finally, the Django-provided base translation in ``django/conf/locale``
- is used as a fallback.
-.. deprecated:: 1.3
- Lookup in the ``locale`` subdirectory of the directory containing your
- settings file (item 3 above) is deprecated since the 1.3 release and will be
- removed in Django 1.5. You can use the :setting:`LOCALE_PATHS` setting
- instead, by listing the absolute filesystem path of such ``locale``
- directory in the setting value.
-.. seealso::
- The translations for literals included in JavaScript assets are looked up
- following a similar but not identical algorithm. See the
- :ref:`javascript_catalog view documentation <javascript_catalog-view>` for
- more details.
-In all cases the name of the directory containing the translation is expected to
-be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``,
-This way, you can write applications that include their own translations, and
-you can override base translations in your project path. Or, you can just build
-a big project out of several apps and put all translations into one big common
-message file specific to the project you are composing. The choice is yours.
-.. note::
- If you're using manually configured settings, as described in
- :ref:`settings-without-django-settings-module`, the ``locale`` directory in
- the project directory will not be examined, since Django loses the ability
- to work out the location of the project directory. (Django normally uses the
- location of the settings file to determine this, and a settings file doesn't
- exist if you're manually configuring your settings.)
-All message file repositories are structured the same way. They are:
-* All paths listed in :setting:`LOCALE_PATHS` in your settings file are
- searched for ``<language>/LC_MESSAGES/django.(po|mo)``
-* ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)`` --
- deprecated, see above.
-* ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
-* ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
-To create message files, you use the :djadmin:` makemessages <makemessages>`
-tool. You only need to be in the same directory where the ``locale/`` directory
-is located. And you use :djadmin:` compilemessages <compilemessages>`
-to produce the binary ``.mo`` files that are used by ``gettext``. Read the
-:doc:`/topics/i18n/localization` document for more details.
-You can also run `` compilemessages``
-to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
-Finally, you should give some thought to the structure of your translation
-files. If your applications need to be delivered to other users and will
-be used in other projects, you might want to use app-specific translations.
-But using app-specific translations and project-specific translations could
-produce weird problems with ``makemessages``: It will traverse all directories
-below the current path and so might put message IDs into a unified, common
-message file for the current project that are already in application message
-The easiest way out is to store applications that are not part of the project
-(and so carry their own translations) outside the project tree. That way,
-`` makemessages``, when ran on a project level will only extract
-strings that are connected to your explicit project and not strings that are
-distributed independently.
-Using translations outside views and templates
-While Django provides a rich set of i18n tools for use in views and templates,
-it does not restrict the usage to Django-specific code. The Django translation
-mechanisms can be used to translate arbitrary texts to any language that is
-supported by Django (as long as an appropriate translation catalog exists, of
-course). You can load a translation catalog, activate it and translate text to
-language of your choice, but remember to switch back to original language, as
-activating a translation catalog is done on per-thread basis and such change
-will affect code running in the same thread.
-For example::
- from django.utils import translation
- def welcome_translated(language):
- cur_language = translation.get_language()
- try:
- translation.activate(language)
- text = translation.ugettext('welcome')
- finally:
- translation.activate(cur_language)
- return text
-Calling this function with the value 'de' will give you ``"Willkommen"``,
-regardless of :setting:`LANGUAGE_CODE` and language set by middleware.
-Functions of particular interest are ``django.utils.translation.get_language()``
-which returns the language used in the current thread,
-``django.utils.translation.activate()`` which activates a translation catalog
-for the current thread, and ``django.utils.translation.check_for_language()``
-which checks if the given language is supported by Django.
@@ -18,7 +18,6 @@ you quickly accomplish common tasks.
- i18n
@@ -56,7 +56,7 @@ Browse the following sections to find out how:
- translations
+ localizing
.. _django-users:
@@ -1,15 +1,15 @@
-Submitting and maintaining translations
+Localizing Django
Various parts of Django, such as the admin site and validation error messages,
-are internationalized. This means they display different text depending on each
-user's language setting. For this, Django uses the same internationalization and
-localization infrastructure available to Django applications, described in the
-:doc:`i18n documentation</topics/i18n/index>`.
+are internationalized. This means they display differently depending on each
+user's language or country. For this, Django uses the same internationalization
+and localization infrastructure available to Django applications, described in
+the :doc:`i18n documentation </topics/i18n/index>`.
Translations are contributed by Django users worldwide. The translation work is
coordinated at `Transifex`_.
@@ -45,8 +45,8 @@ do:
For more information about how to use Transifex, read the
`Transifex User Guide`_.
You can also review ``conf/locale/<locale>/``. This file describes
the date, time and numbers formatting particularities of your locale. See
@@ -146,7 +146,7 @@ Django's general catalog in ``django/conf/locale``. If you want localflavor's
texts to be translated, like form fields error messages, you must include
:mod:`django.contrib.localflavor` in the :setting:`INSTALLED_APPS` setting, so
the internationalization system can find the catalog, as explained in
Adding flavors
@@ -1243,7 +1243,7 @@ LOCALE_PATHS
Default: ``()`` (Empty tuple)
A tuple of directories where Django looks for translation files.
-See :ref:`using-translations-in-your-own-projects`.
+See :ref:`how-django-discovers-translations`.
@@ -2038,10 +2038,10 @@ USE_I18N
Default: ``True``
-A boolean that specifies whether Django's internationalization system should be
-enabled. This provides an easy way to turn it off, for performance. If this is
-set to ``False``, Django will make some optimizations so as not to load the
-internationalization machinery.
+A boolean that specifies whether Django's translation system should be enabled.
+This provides an easy way to turn it off, for performance. If this is set to
+``False``, Django will make some optimizations so as not to load the
+translation machinery.
See also :setting:`USE_L10N`
@@ -2054,9 +2054,9 @@ USE_L10N
Default: ``False``
-A boolean that specifies if data will be localized by default or not. If this
-is set to ``True``, e.g. Django will display numbers and dates using the
-format of the current locale.
+A boolean that specifies if localized formatting of data will be enabled by
+default or not. If this is set to ``True``, e.g. Django will display numbers and
+dates using the format of the current locale.
See also :setting:`USE_I18N` and :setting:`LANGUAGE_CODE`
@@ -455,7 +455,7 @@ appropriate entities.
:synopsis: Internationalization support.
For a complete discussion on the usage of the following see the
-:doc:`Internationalization documentation </topics/i18n/internationalization>`.
+:doc:`translation documentation </topics/i18n/translation>`.
.. function:: gettext(message)
@@ -494,12 +494,9 @@ more on these decorators.
.. versionadded:: 1.2
If :setting:`USE_I18N` is set to ``True`` then the generated cache key will
-include the name of the active :term:`language<language code>`.
-This allows you to easily cache multilingual sites without having to create
-the cache key yourself.
-See :doc:`/topics/i18n/deployment` for more on how Django discovers the active
+include the name of the active :term:`language<language code>` -- see also
+:ref:`how-django-discovers-language-preference`). This allows you to easily
+cache multilingual sites without having to create the cache key yourself.
__ `Controlling cache: Using other headers`_
Oops, something went wrong.

0 comments on commit 67e6e0f

Please sign in to comment.