Permalink
Browse files

Fixed #10260 - Refactored internationalization documentation. Thanks,…

… Ramiro Morales.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12440 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 9b630a0 commit f93f056c32f614c9a130ec66824d94ec20526cdf @jezdez jezdez committed Feb 16, 2010
@@ -306,7 +306,7 @@
# http://docs.djangoproject.com/en/dev/ref/templates/builtins/#now
MONTH_DAY_FORMAT = 'F j'
-# Default shortformatting for date objects. See all available format strings here:
+# Default short formatting for date objects. See all available format strings here:
# http://docs.djangoproject.com/en/dev/ref/templates/builtins/#now
SHORT_DATE_FORMAT = 'm/d/Y'
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,11 @@ 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.
+ * Optionally, review and update the ``conf/locale/<locale>/formats.py``
+ file to describe the date, time and numbers formatting particularities of
+ your locale. See :ref:`format-localization` for details.
+
+ * 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
@@ -883,8 +883,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
@@ -911,9 +911,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.
@@ -948,7 +950,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
View
@@ -516,6 +516,19 @@ documentation <ref-contrib-syndication>`.
.. _RSS best practices: http://www.rssboard.org/rss-profile
+Technical message IDs
+---------------------
+
+Up to version 1.1 Django used :ref:`technical message IDs<technical-messages>`
+to provide localizers the possibility to translate date and time formats. They
+were translatable :term:`translation strings <translation string>` that could
+be recognized because they were all upper case (for example
+``DATETIME_FORMAT``, ``DATE_FORMAT``, ``TIME_FORMAT``). They have been
+deprecated in favor of the new :ref:`Format localization
+<format-localization>` infrastructure that allows localizers to specify that
+information in a ``formats.py`` file in the corresponding
+``django/conf/locale/<locale name>/`` directory.
+
What's new in Django 1.2
========================
@@ -577,15 +590,15 @@ added support for comparison operators. No longer will you have to type:
.. code-block:: html+django
{% ifnotequal a b %}
- ...
+ ...
{% endifnotequal %}
You can now do this:
.. code-block:: html+django
{% if a != b %}
- ...
+ ...
{% endif %}
There's really no reason to use ``{% ifequal %}`` or ``{% ifnotequal %}``
Oops, something went wrong. Retry.

0 comments on commit f93f056

Please sign in to comment.