Permalink
Browse files

[1.1.X] Fixed #10260 - Refactored internationalization documentation.…

… Thanks, Ramiro Morales.

Partial backport of r12440.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@12449 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 4384b16 commit a23edb643bdbfde6be1e0a63d1a8bd2a1be13710 @jezdez jezdez committed Feb 16, 2010
View
@@ -0,0 +1,72 @@
+.. _howto-i18n:
+
+.. _using-translations-in-your-own-projects:
+
+===============================================
+Using internationalization in your own projects
+===============================================
+
+At runtime, Django looks for translations by following this algorithm:
+
+ * First, it looks for a ``locale`` directory in the application directory
+ of the view that's being called. If it finds a translation for the
+ selected language, the translation will be installed.
+ * Next, it looks for a ``locale`` directory in the project directory. If it
+ finds a translation, the translation will be installed.
+ * Finally, it checks the Django-provided base translation in
+ ``django/conf/locale``.
+
+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 project
+message file. 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:
+
+ * ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
+ * ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
+ * All paths listed in ``LOCALE_PATHS`` in your settings file are
+ searched in that order for ``<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
+:ref:`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.
+
+Application message files are a bit complicated to discover -- they need the
+:class:`~django.middleware.locale.LocaleMiddleware`. If you don't use the
+middleware, only the Django message files and project message files will be
+installed and available at runtime.
+
+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 translations could produce
+weird problems with ``makemessages``: It will traverse all directories below
+the current path and so might put message IDs into the project message file
+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`` on the project level will only translate
+strings that are connected to your explicit project and not strings that are
+distributed independently.
@@ -20,6 +20,7 @@ you quickly accomplish common tasks.
deployment/index
error-reporting
initial-data
+ i18n
jython
legacy-databases
outputting-csv
@@ -402,15 +402,18 @@ translated, here's what to do:
* Join the `Django i18n mailing list`_ and introduce yourself.
+ * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
+
* Create translations using the methods described in the
- :ref:`i18n documentation <topics-i18n>`. For this you will use the
- ``django-admin.py makemessages`` tool. In this particular case it should
- be run from the top-level ``django`` directory of the Django source tree.
+ :ref:`localization documentation <topics-i18n-localization>`. For this
+ you will use the ``django-admin.py makemessages`` tool. In this
+ particular case it should be run from the top-level ``django`` directory
+ of the Django source tree.
The script runs over the entire Django source tree and pulls out all
strings marked for translation. It creates (or updates) a message file in
- the directory ``conf/locale`` (for example for ``pt-BR``, the file will be
- ``conf/locale/pt-br/LC_MESSAGES/django.po``).
+ the directory ``conf/locale`` (for example for ``pt_BR``, the file will be
+ ``conf/locale/pt_BR/LC_MESSAGES/django.po``).
* Make sure that ``django-admin.py compilemessages -l <lang>`` runs without
producing any warnings.
@@ -419,7 +422,7 @@ translated, here's what to do:
``-d djangojs`` command line option to the ``django-admin.py``
invocations).
- * Create a diff of the ``.po`` file(s) against the current Subversion trunk.
+ * Create a diff against the current Subversion trunk.
* Open a ticket in Django's ticket system, set its ``Component`` field to
``Translations``, and attach the patch to it.
View
@@ -610,8 +610,8 @@ LANGUAGE_CODE
Default: ``'en-us'``
A string representing the language code for this installation. This should be in
-standard language format. For example, U.S. English is ``"en-us"``. See
-:ref:`topics-i18n`.
+standard :term:`language format<language code>`. For example, U.S. English is
+``"en-us"``. See :ref:`topics-i18n`.
.. setting:: LANGUAGE_COOKIE_NAME
@@ -638,9 +638,11 @@ see the current list of translated languages by looking in
.. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py
-The list is a tuple of two-tuples in the format (language code, language
-name) -- for example, ``('ja', 'Japanese')``. This specifies which languages
-are available for language selection. See :ref:`topics-i18n`.
+The list is a tuple of two-tuples in the format ``(language code, language
+name)``, the ``language code`` part should be a
+:term:`language name<language code>` -- for example, ``('ja', 'Japanese')``.
+This specifies which languages are available for language selection. See
+:ref:`topics-i18n`.
Generally, the default value should suffice. Only set this setting if you want
to restrict language selection to a subset of the Django-provided languages.
@@ -675,7 +677,7 @@ LOCALE_PATHS
Default: ``()`` (Empty tuple)
A tuple of directories where Django looks for translation files.
-See :ref:`translations-in-your-own-projects`.
+See :ref:`using-translations-in-your-own-projects`.
.. setting:: LOGIN_REDIRECT_URL
Oops, something went wrong.

0 comments on commit a23edb6

Please sign in to comment.