Source

djangofrdoc / topics / i18n / localization.txt

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
============
Localization
============

This document covers three localization-related topics: `Creating language
files`_ , `locale aware date, time and numbers input/output in forms`_,
and `controlling localization in templates`_.

.. _`Creating language files`: how-to-create-language-files_
.. _`locale aware date, time and numbers input/output in forms`: format-localization_
.. _`controlling localization in templates`: topic-l10n-templates_

.. seealso::

    The :doc:`/howto/i18n` document included with the Django HOW-TO documents collection.

.. _how-to-create-language-files:

How to create language files
============================

Once the string literals of an application have been tagged for later
translation, the translation themselves need to be written (or obtained). Here's
how that works.

.. _locale-restrictions:

.. admonition:: Locale restrictions

    Django does not support localizing your application into a locale for which
    Django itself has not been translated. In this case, it will ignore your
    translation files. If you were to try this and Django supported it, you
    would inevitably see a mixture of translated strings (from your application)
    and English strings (from Django itself). If you want to support a locale
    for your application that is not already part of Django, you'll need to make
    at least a minimal translation of the Django core.

    A good starting point is to copy the Django English ``.po`` file and to
    translate at least some :term:`translation strings <translation string>`.

Message files
-------------

The first step is to create a :term:`message file` for a new language. A message
file is a plain-text file, representing a single language, that contains all
available translation strings and how they should be represented in the given
language. Message files have a ``.po`` file extension.

Django comes with a tool, ``django-admin.py makemessages``, that automates the
creation and upkeep of these files.

.. admonition:: A note to Django veterans

    The old tool ``bin/make-messages.py`` has been moved to the command
    ``django-admin.py makemessages`` to provide consistency throughout Django.

.. admonition:: Gettext utilities

    The ``makemessages`` command (and ``compilemessages`` discussed later) use
    commands from the GNU gettext toolset: ``xgettext``, ``msgfmt``,
    ``msgmerge`` and ``msguniq``.

    .. versionchanged:: 1.2

    The minimum version of the ``gettext`` utilities supported is 0.15.

To create or update a message file, run this command::

    django-admin.py makemessages -l de

...where ``de`` is the language code for the message file you want to create.
The language code, in this case, is in :term:`locale format<locale name>`. For
example, it's ``pt_BR`` for Brazilian Portuguese and ``de_AT`` for Austrian
German.

The script should be run from one of two places:

    * The root directory of your Django project.
    * The root directory of your Django app.

The script runs over your project source tree or your application source tree
and pulls out all strings marked for translation. It creates (or updates) a
message file in the directory ``locale/LANG/LC_MESSAGES``. In the ``de``
example, the file will be ``locale/de/LC_MESSAGES/django.po``.

By default ``django-admin.py makemessages`` examines every file that has the
``.html`` file extension. In case you want to override that default, use the
``--extension`` or ``-e`` option to specify the file extensions to examine::

    django-admin.py makemessages -l de -e txt

Separate multiple extensions with commas and/or use ``-e`` or ``--extension``
multiple times::

    django-admin.py makemessages -l de -e html,txt -e xml

When :ref:`creating message files from JavaScript source code
<creating-message-files-from-js-code>` you need to use the special 'djangojs'
domain, **not** ``-e js``.

.. admonition:: No gettext?

    If you don't have the ``gettext`` utilities installed, ``django-admin.py
    makemessages`` will create empty files. If that's the case, either install
    the ``gettext`` utilities or just copy the English message file
    (``locale/en/LC_MESSAGES/django.po``) if available and use it as a starting
    point; it's just an empty translation file.

.. admonition:: Working on Windows?

   If you're using Windows and need to install the GNU gettext utilities so
   ``django-admin makemessages`` works see :ref:`gettext_on_windows` for more
   information.

The format of ``.po`` files is straightforward. Each ``.po`` file contains a
small bit of metadata, such as the translation maintainer's contact
information, but the bulk of the file is a list of **messages** -- simple
mappings between translation strings and the actual translated text for the
particular language.

For example, if your Django app contained a translation string for the text
``"Welcome to my site."``, like so::

    _("Welcome to my site.")

...then ``django-admin.py makemessages`` will have created a ``.po`` file
containing the following snippet -- a message::

    #: path/to/python/module.py:23
    msgid "Welcome to my site."
    msgstr ""

A quick explanation:

    * ``msgid`` is the translation string, which appears in the source. Don't
      change it.
    * ``msgstr`` is where you put the language-specific translation. It starts
      out empty, so it's your responsibility to change it. Make sure you keep
      the quotes around your translation.
    * As a convenience, each message includes, in the form of a comment line
      prefixed with ``#`` and located above the ``msgid`` line, the filename and
      line number from which the translation string was gleaned.

Long messages are a special case. There, the first string directly after the
``msgstr`` (or ``msgid``) is an empty string. Then the content itself will be
written over the next few lines as one string per line. Those strings are
directly concatenated. Don't forget trailing spaces within the strings;
otherwise, they'll be tacked together without whitespace!

.. admonition:: Mind your charset

    When creating a PO file with your favorite text editor, first edit
    the charset line (search for ``"CHARSET"``) and set it to the charset
    you'll be using to edit the content. Due to the way the ``gettext`` tools
    work internally and because we want to allow non-ASCII source strings in
    Django's core and your applications, you **must** use UTF-8 as the encoding
    for your PO file. This means that everybody will be using the same
    encoding, which is important when Django processes the PO files.

To reexamine all source code and templates for new translation strings and
update all message files for **all** languages, run this::

    django-admin.py makemessages -a

Compiling message files
-----------------------

After you create your message file -- and each time you make changes to it --
you'll need to compile it into a more efficient form, for use by ``gettext``.
Do this with the ``django-admin.py compilemessages`` utility.

This tool runs over all available ``.po`` files and creates ``.mo`` files, which
are binary files optimized for use by ``gettext``. In the same directory from
which you ran ``django-admin.py makemessages``, run ``django-admin.py
compilemessages`` like this::

   django-admin.py compilemessages

That's it. Your translations are ready for use.

.. admonition:: A note to Django veterans

    The old tool ``bin/compile-messages.py`` has been moved to the command
    ``django-admin.py compilemessages`` to provide consistency throughout
    Django.

.. admonition:: Working on Windows?

   If you're using Windows and need to install the GNU gettext utilities so
   ``django-admin compilemessages`` works see :ref:`gettext_on_windows` for more
   information.

.. admonition:: .po files: Encoding and BOM usage.

   Django only supports ``.po`` files encoded in UTF-8 and without any BOM
   (Byte Order Mark) so if your text editor adds such marks to the beginning of
   files by default then you will need to reconfigure it.

.. _creating-message-files-from-js-code:

Creating message files from JavaScript source code
==================================================

You create and update the message files the same way as the other Django message
files -- with the ``django-admin.py makemessages`` tool. The only difference is
you need to provide a ``-d djangojs`` parameter, like this::

    django-admin.py makemessages -d djangojs -l de

This would create or update the message file for JavaScript for German.
After updating message files, just run ``django-admin.py compilemessages``
the same way as you do with normal Django message files.

.. _gettext_on_windows:

``gettext`` on Windows
======================

This is only needed for people who either want to extract message IDs or compile
message files (``.po``). Translation work itself just involves editing existing
files of this type, but if you want to create your own message files, or want to
test or compile a changed message file, you will need the ``gettext`` utilities:

    * Download the following zip files from the GNOME servers
      http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/ or from one
      of its mirrors_

      * ``gettext-runtime-X.zip``
      * ``gettext-tools-X.zip``

      ``X`` is the version number, we are requiring ``0.15`` or higher.

    * Extract the contents of the ``bin\`` directories in both files to the
      same folder on your system (i.e. ``C:\Program Files\gettext-utils``)

    * Update the system PATH:

      * ``Control Panel > System > Advanced > Environment Variables``.
      * In the ``System variables`` list, click ``Path``, click ``Edit``.
      * Add ``;C:\Program Files\gettext-utils\bin`` at the end of the
        ``Variable value`` field.

.. _mirrors: http://ftp.gnome.org/pub/GNOME/MIRRORS

You may also use ``gettext`` binaries you have obtained elsewhere, so long as
the ``xgettext --version`` command works properly. Do not attempt to use Django
translation utilities with a ``gettext`` package if the command ``xgettext
--version`` entered at a Windows command prompt causes a popup window saying
"xgettext.exe has generated errors and will be closed by Windows".

.. _format-localization:

Format localization
===================

.. versionadded:: 1.2

Django's formatting system is disabled by default. To enable it, it's
necessary to set :setting:`USE_L10N = True <USE_L10N>` in your settings file.

.. note::
    The default :file:`settings.py` file created by
    :djadmin:`django-admin.py startproject <startproject>` includes
    :setting:`USE_L10N = True <USE_L10N>` for convenience.

When using Django's formatting system, dates and numbers on templates will be
displayed using the format specified for the current locale. Two users
accessing the same content, but in different language, will see date and
number fields formatted in different ways, depending on the format for their
current locale.

Django will also use localized formats when parsing data in forms. That means
Django uses different formats for different locales when guessing the format
used by the user when inputting data on forms.

.. note::
    Django uses different formats for displaying data to those it uses for
    parsing data. Most notably, the formats for parsing dates can't use the
    ``%a`` (abbreviated weekday name), ``%A`` (full weekday name),
    ``%b`` (abbreviated month name), ``%B`` (full month name),
    or ``%p`` (AM/PM).

To enable a form field to localize input and output data simply use its
``localize`` argument::

    class CashRegisterForm(forms.Form):
       product = forms.CharField()
       revenue = forms.DecimalField(max_digits=4, decimal_places=2, localize=True)

Creating custom format files
----------------------------

Django provides format definitions for many locales, but sometimes you might
want to create your own, because a format files doesn't exist for your locale,
or because you want to overwrite some of the values.

To use custom formats, first thing to do, is to specify the path where you'll
place format files. To do that, just set your :setting:`FORMAT_MODULE_PATH`
setting to the path (in the format ``'foo.bar.baz``) where format files
will exists.

Files are not placed directly in this directory, but in a directory named as
the locale, and must be named ``formats.py``.

To customize the English formats, a structure like this would be needed::

    mysite/
        formats/
            __init__.py
            en/
                __init__.py
                formats.py

where :file:`formats.py` contains custom format definitions. For example::

    THOUSAND_SEPARATOR = ' '

to use a space as a thousand separator, instead of the default for English,
a comma.

.. _topic-l10n-templates:

Controlling localization in templates
=====================================

When you have enabled localization using :setting:`USE_L10N`, Django
will try to use a locale specific format whenever it outputs a value
in a template.

However, it may not always be appropriate to use localized values --
for example, if you're outputting Javascript or XML that is designed
to be machine-readable, you will always want unlocalized values. You
may also want to use localization in selected templates, rather than
using localization everywhere.

To allow for fine control over the use of localization, Django
provides the ``l10n`` template library that contains the following
tags and filters.

Template tags
-------------

.. templatetag:: localize

localize
~~~~~~~~

.. versionadded:: 1.3

Enables or disables localization of template variables in the
contained block.

This tag allows a more fine grained control of localization than
:setting:`USE_L10N`.

To activate or deactivate localization for a template block, use::

    {% localize on %}
        {{ value }}
    {% endlocalize %}

    {% localize off %}
        {{ value }}
    {% endlocalize %}

.. note::

    The value of :setting:`USE_L10N` is not respected inside of a
    `{% localize %}` block.

See :tfilter:`localized` and :tfilter:`unlocalized` for a template filter that will
do the same job on a per-variable basis.

Template filters
----------------

.. templatefilter:: localize

localize
~~~~~~~~

.. versionadded:: 1.3

Forces localization of a single value.

For example::

    {{ value|localize }}

To disable localization on a single value, use :tfilter:`unlocalize`. To control
localization over a large section of a template, use the :ttag:`localize` template
tag.


.. templatefilter:: unlocalize

unlocalize
~~~~~~~~~~

.. versionadded:: 1.3

Forces a single value to be printed without localization.

For example::

    {{ value|unlocalize }}

To force localization of a single value, use :tfilter:`localize`. To
control localization over a large section of a template, use the
:ttag:`localize` template tag.