diff options
Diffstat (limited to 'parts/django/docs/topics/i18n/localization.txt')
| -rw-r--r-- | parts/django/docs/topics/i18n/localization.txt | 317 |
1 files changed, 0 insertions, 317 deletions
diff --git a/parts/django/docs/topics/i18n/localization.txt b/parts/django/docs/topics/i18n/localization.txt deleted file mode 100644 index 38d74e6..0000000 --- a/parts/django/docs/topics/i18n/localization.txt +++ /dev/null @@ -1,317 +0,0 @@ -============ -Localization -============ - -This document covers two localization-related topics: `Creating language -files`_ and `locale aware date, time and numbers input/output in forms`_ - -.. _`Creating language files`: how-to-create-language-files_ -.. _`locale aware date, time and numbers input/output in forms`: format-localization_ - -.. 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. |