Skip to content

Commit f93f056

Browse files
jezdezjezdez
committed
Fixed #10260 - Refactored internationalization documentation. Thanks, Ramiro Morales.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@12440 bcc190cf-cafb-0310-a4f2-bffc1f526a37
1 parent 9b630a0 commit f93f056

File tree

12 files changed

+1293
-1160
lines changed

12 files changed

+1293
-1160
lines changed

‎django/conf/global_settings.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -306,7 +306,7 @@
306306
# http://docs.djangoproject.com/en/dev/ref/templates/builtins/#now
307307
MONTH_DAY_FORMAT = 'F j'
308308

309-
# Default shortformatting for date objects. See all available format strings here:
309+
# Default short formatting for date objects. See all available format strings here:
310310
# http://docs.djangoproject.com/en/dev/ref/templates/builtins/#now
311311
SHORT_DATE_FORMAT = 'm/d/Y'
312312

‎docs/howto/i18n.txt

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
.. _howto-i18n:
2+
3+
.. _using-translations-in-your-own-projects:
4+
5+
===============================================
6+
Using internationalization in your own projects
7+
===============================================
8+
9+
At runtime, Django looks for translations by following this algorithm:
10+
11+
* First, it looks for a ``locale`` directory in the application directory
12+
of the view that's being called. If it finds a translation for the
13+
selected language, the translation will be installed.
14+
* Next, it looks for a ``locale`` directory in the project directory. If it
15+
finds a translation, the translation will be installed.
16+
* Finally, it checks the Django-provided base translation in
17+
``django/conf/locale``.
18+
19+
In all cases the name of the directory containing the translation is expected to
20+
be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``,
21+
etc.
22+
23+
This way, you can write applications that include their own translations, and
24+
you can override base translations in your project path. Or, you can just build
25+
a big project out of several apps and put all translations into one big project
26+
message file. The choice is yours.
27+
28+
.. note::
29+
30+
If you're using manually configured settings, as described in
31+
:ref:`settings-without-django-settings-module`, the ``locale`` directory in
32+
the project directory will not be examined, since Django loses the ability
33+
to work out the location of the project directory. (Django normally uses the
34+
location of the settings file to determine this, and a settings file doesn't
35+
exist if you're manually configuring your settings.)
36+
37+
All message file repositories are structured the same way. They are:
38+
39+
* ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
40+
* ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
41+
* All paths listed in ``LOCALE_PATHS`` in your settings file are
42+
searched in that order for ``<language>/LC_MESSAGES/django.(po|mo)``
43+
* ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
44+
45+
To create message files, you use the :djadmin:`django-admin.py makemessages <makemessages>`
46+
tool. You only need to be in the same directory where the ``locale/`` directory
47+
is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>`
48+
to produce the binary ``.mo`` files that are used by ``gettext``. Read the
49+
:ref:`topics-i18n-localization` document for more details.
50+
51+
You can also run ``django-admin.py compilemessages --settings=path.to.settings``
52+
to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
53+
setting.
54+
55+
Application message files are a bit complicated to discover -- they need the
56+
:class:`~django.middleware.locale.LocaleMiddleware`. If you don't use the
57+
middleware, only the Django message files and project message files will be
58+
installed and available at runtime.
59+
60+
Finally, you should give some thought to the structure of your translation
61+
files. If your applications need to be delivered to other users and will
62+
be used in other projects, you might want to use app-specific translations.
63+
But using app-specific translations and project translations could produce
64+
weird problems with ``makemessages``: It will traverse all directories below
65+
the current path and so might put message IDs into the project message file
66+
that are already in application message files.
67+
68+
The easiest way out is to store applications that are not part of the project
69+
(and so carry their own translations) outside the project tree. That way,
70+
``django-admin.py makemessages`` on the project level will only translate
71+
strings that are connected to your explicit project and not strings that are
72+
distributed independently.

‎docs/howto/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ you quickly accomplish common tasks.
2020
deployment/index
2121
error-reporting
2222
initial-data
23+
i18n
2324
jython
2425
legacy-databases
2526
outputting-csv

‎docs/internals/contributing.txt

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -402,15 +402,18 @@ translated, here's what to do:
402402

403403
* Join the `Django i18n mailing list`_ and introduce yourself.
404404

405+
* Make sure you read the notes about :ref:`specialties-of-django-i18n`.
406+
405407
* Create translations using the methods described in the
406-
:ref:`i18n documentation <topics-i18n>`. For this you will use the
407-
``django-admin.py makemessages`` tool. In this particular case it should
408-
be run from the top-level ``django`` directory of the Django source tree.
408+
:ref:`localization documentation <topics-i18n-localization>`. For this
409+
you will use the ``django-admin.py makemessages`` tool. In this
410+
particular case it should be run from the top-level ``django`` directory
411+
of the Django source tree.
409412

410413
The script runs over the entire Django source tree and pulls out all
411414
strings marked for translation. It creates (or updates) a message file in
412-
the directory ``conf/locale`` (for example for ``pt-BR``, the file will be
413-
``conf/locale/pt-br/LC_MESSAGES/django.po``).
415+
the directory ``conf/locale`` (for example for ``pt_BR``, the file will be
416+
``conf/locale/pt_BR/LC_MESSAGES/django.po``).
414417

415418
* Make sure that ``django-admin.py compilemessages -l <lang>`` runs without
416419
producing any warnings.
@@ -419,7 +422,11 @@ translated, here's what to do:
419422
``-d djangojs`` command line option to the ``django-admin.py``
420423
invocations).
421424

422-
* Create a diff of the ``.po`` file(s) against the current Subversion trunk.
425+
* Optionally, review and update the ``conf/locale/<locale>/formats.py``
426+
file to describe the date, time and numbers formatting particularities of
427+
your locale. See :ref:`format-localization` for details.
428+
429+
* Create a diff against the current Subversion trunk.
423430

424431
* Open a ticket in Django's ticket system, set its ``Component`` field to
425432
``Translations``, and attach the patch to it.

‎docs/ref/settings.txt

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -883,8 +883,8 @@ LANGUAGE_CODE
883883
Default: ``'en-us'``
884884

885885
A string representing the language code for this installation. This should be in
886-
standard language format. For example, U.S. English is ``"en-us"``. See
887-
:ref:`topics-i18n`.
886+
standard :term:`language format<language code>`. For example, U.S. English is
887+
``"en-us"``. See :ref:`topics-i18n`.
888888

889889
.. setting:: LANGUAGE_COOKIE_NAME
890890

@@ -911,9 +911,11 @@ see the current list of translated languages by looking in
911911

912912
.. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py
913913

914-
The list is a tuple of two-tuples in the format (language code, language
915-
name) -- for example, ``('ja', 'Japanese')``. This specifies which languages
916-
are available for language selection. See :ref:`topics-i18n`.
914+
The list is a tuple of two-tuples in the format ``(language code, language
915+
name)``, the ``language code`` part should be a
916+
:term:`language name<language code>` -- for example, ``('ja', 'Japanese')``.
917+
This specifies which languages are available for language selection. See
918+
:ref:`topics-i18n`.
917919

918920
Generally, the default value should suffice. Only set this setting if you want
919921
to restrict language selection to a subset of the Django-provided languages.
@@ -948,7 +950,7 @@ LOCALE_PATHS
948950
Default: ``()`` (Empty tuple)
949951

950952
A tuple of directories where Django looks for translation files.
951-
See :ref:`translations-in-your-own-projects`.
953+
See :ref:`using-translations-in-your-own-projects`.
952954

953955
.. setting:: LOGIN_REDIRECT_URL
954956

‎docs/releases/1.2.txt

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -516,6 +516,19 @@ documentation <ref-contrib-syndication>`.
516516

517517
.. _RSS best practices: http://www.rssboard.org/rss-profile
518518

519+
Technical message IDs
520+
---------------------
521+
522+
Up to version 1.1 Django used :ref:`technical message IDs<technical-messages>`
523+
to provide localizers the possibility to translate date and time formats. They
524+
were translatable :term:`translation strings <translation string>` that could
525+
be recognized because they were all upper case (for example
526+
``DATETIME_FORMAT``, ``DATE_FORMAT``, ``TIME_FORMAT``). They have been
527+
deprecated in favor of the new :ref:`Format localization
528+
<format-localization>` infrastructure that allows localizers to specify that
529+
information in a ``formats.py`` file in the corresponding
530+
``django/conf/locale/<locale name>/`` directory.
531+
519532
What's new in Django 1.2
520533
========================
521534

@@ -577,15 +590,15 @@ added support for comparison operators. No longer will you have to type:
577590
.. code-block:: html+django
578591

579592
{% ifnotequal a b %}
580-
...
593+
...
581594
{% endifnotequal %}
582595

583596
You can now do this:
584597

585598
.. code-block:: html+django
586599

587600
{% if a != b %}
588-
...
601+
...
589602
{% endif %}
590603

591604
There's really no reason to use ``{% ifequal %}`` or ``{% ifnotequal %}``

0 commit comments

Comments
 (0)