Permalink
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: http://code.djangoproject.com/svn/django/trunk@17026 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 4f00a2d commit 67e6e0fcf35d93f88bfb1a4cbf5c6008d99dd923 @aaugustin aaugustin committed Oct 22, 2011
View
@@ -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``,
-etc.
-
-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:`django-admin.py makemessages <makemessages>`
-tool. You only need to be in the same directory where the ``locale/`` directory
-is located. And you use :djadmin:`django-admin.py 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 ``django-admin.py compilemessages --settings=path.to.settings``
-to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
-setting.
-
-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
-files.
-
-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,
-``django-admin.py 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.
deployment/index
error-reporting
initial-data
- i18n
jython
legacy-databases
outputting-csv
@@ -56,7 +56,7 @@ Browse the following sections to find out how:
triaging-tickets
writing-code/index
writing-documentation
- translations
+ localizing
committing-code
.. _django-users: http://groups.google.com/group/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>`.
-Internationalization
---------------------
+Translations
+------------
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`_.
-Localization
-------------
+Formats
+-------
You can also review ``conf/locale/<locale>/formats.py``. 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
-:ref:`using-translations-in-your-own-projects`.
+:ref:`how-django-discovers-translations`.
Adding flavors
==============
View
@@ -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`.
Example::
@@ -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`
View
@@ -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
-language.
+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.