Fixed #17087 -- Re-organized the i18n docs to reduce confusion between 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

2 files changed, 0 insertions, 122 deletions

diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt
deleted file mode 100644
index 7310e52591..0000000000
--- a/docs/howto/i18n.txt
+++ /dev/null
@@ -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.
diff --git a/docs/howto/index.txt b/docs/howto/index.txt
index 49d0644034..3616f7ae16 100644
--- a/docs/howto/index.txt
+++ b/docs/howto/index.txt
@@ -18,7 +18,6 @@ you quickly accomplish common tasks.
    deployment/index
    error-reporting
    initial-data
-   i18n
    jython
    legacy-databases
    outputting-csv