Changeset 1087

Timestamp:

11/04/05 22:22:25 (3 years ago)

Author:

adrian

Message:

Moderately heavy rewrite of docs/translation.txt

Files:

• django/trunk/docs/translation.txt (modified) (10 diffs)

django/trunk/docs/translation.txt

@@ -1 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-    from django.utils.translation import gettext
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-For example, to translate a model's ``help_text``, do the following::
@@ -108 +156 @@
-            verbose_name_plural = _('mythings')
-
-
-
-
+
+
+
+
+
+
+
-    def hello_world(request, count):
-        from django.utils.translation import ngettext
-        page = ngettext('there is %(count)d object', 'there are %(count)d objects', count) % {
-            'count': count,
@@ -118 +169 @@
-        return HttpResponse(page)
-
-
-
+
+
+
+
+
+
-
-Using translations in Django templates uses two template tags and a slightly
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-    {% endblocktrans %}
-
-
-
+
+
+
-
-    {% blocktrans count list|counted as counter %}
@@ -154 +214 @@
-    {% endblocktrans %}
-
- all block translations and inline translations are translated into
-the actual gettext/ngettext
+, all block and inline translations use the appropriate
+``gettext`` / ``ngettext``
-
-Each ``DjangoContext`` has access to two translation-specific variables:
@@ -170 +230 @@
-    {% get_available_languages as LANGUAGES %}
-
-
-
-
-
-
-
+
+
+
+
+
-
-    {% some_special_tag _("Page not found") value|yesno:_("yes,no") %}
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-    <input name="next" type="hidden" value="/next/page/" />
-    <select name="language">
@@ -200 +472 @@
-    </form>
-
-When a user submits the form, his chosen language will be saved in a cookie,
-and he'll be redirected either to the URL specified in the ``next`` field, or,
-if ``next`` is empty, to the URL in the ``Referer`` header. If the ``Referer``
-is blank -- say, if a user's browser suppresses that header -- then the user
-will be redirected to ``/`` (the site root) as a fallback.
-
-Activate the ``setlang`` redirect view by adding the following line to your
-URLconf::
-
-    (r'^i18n/', include('django.conf.urls.i18n'),
-
-Note that this example makes the view available at ``/i18n/setlang/``.
-
-How language preference is discovered
-=====================================
-
-Django has a very flexible model of deciding which language should be used --
-installation-wide, for a particular user, or both.
-
-To set an installation-wide language preference, set ``LANGUAGE_CODE`` in your
-settings file. Django uses this language as the default translation -- the
-final attempt if no other translator finds a translation.
-
-If all you want to do is run Django with your native language, and a language
-file is available for your language, all you need to do is set
-``LANGUAGE_CODE``.
-
-If you want to let each individual user specify which language he or she
-prefers, use ``LocaleMiddleware``. ``LocaleMiddleware`` enables language
-selection based on data from the request. It lets each user have his or her own
-setting.
-
-To use ``LocaleMiddleware``, add ``'django.middleware.locale.LocaleMiddleware'``
-to your ``MIDDLEWARE_CLASSES`` setting. Because middleware order matters, you
-should follow these guidelines:
-
-    * Make sure it's one of the first middlewares installed.
-    * It should come after ``SessionMiddleware``, because ``LocaleMiddleware``
-      makes use of session data.
-
-For example, your ``MIDDLEWARE_CLASSES`` might look like this::
-
-    MIDDLEWARE_CLASSES = (
-       'django.middleware.sessions.SessionMiddleware',
-       'django.middleware.locale.LocaleMiddleware',
-       'django.middleware.common.CommonMiddleware',
-    )
-
-``LocaleMiddleware`` tries to determine the user's language preference by
-following this algorithm:
-
-    * First, it looks for a ``django_language`` key in the the current user's
-      session.
-    * Failing that, it looks for a cookie called ``django_language``.
-    * Failing that, it looks at the ``Accept-Language`` HTTP header. This
-      header is sent by your browser and tells the server which language(s) you
-      prefer, in order by priority. Django tries each language in the header
-      until it finds one with available translations.
-    * Failing that, it uses the global ``LANGUAGE_CODE`` setting.
-
-Notes:
-
-    * In each of these places, the language preference is expected to be in the
-      standard language format, as a string. For example, Brazilian is
-      ``pt-br``.
-    * If a base language is available but the sublanguage specified is not,
-      Django uses the base language. For example, if a user specifies ``de-at``
-      (Austrian German) but Django only has ``de`` available, Django uses
-      ``de``.
-
-Once ``LocaleMiddleware`` determines the user's preference, it makes this
-preference available as ``request.LANGUAGE_CODE`` for each `request object`_.
-Feel free to read this value in your view code. Here's a simple example::
-
-    def hello_world(request, count):
-        if request.LANGUAGE_CODE == 'de-at':
-            return HttpResponse("You prefer to read Austrian German.")
-        else:
-            return HttpResponse("You prefer to read another language.")
-
-Note that, with static (middleware-less) translation, the language is in
-``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's
-in ``request.LANGUAGE_CODE``.
-
-.. _request object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects
-
-Creating language files
-=======================
-
-So, you've tagged all of your strings for later translation. But you need to
-write the translations themselves.
-
-They need to be in a format grokable by ``gettext``. You need to update them.
-You may need to create new ones for new languages. This section shows you how
-to do it.
-
-Creating message files
-----------------------
-
-The first step is to create a message file for a new language. Django comes
-with a tool, ``make-messages.py``, that automates this.
-
-To run it on the Django source tree, navigate to the ``django`` directory
-itself -- not a Subversion check out, but the one linked to via ``$PYTHONPATH``
-or located somewhere on that path.
-
-Then run this command::
-
-    bin/make-messages.py -l de
-
-...where ``de`` is the language code for the message file you want to create.
-
-This script runs over the entire Django source tree and pulls out all strings
-marked for translation, creating or updating the language's message file.
-
-When it's done, it will have created (or updated) a message file under the
-directory ``conf/locale``. In this example, the file will be
-``conf/locale/de/LC_MESSAGES/django.po``.
-
-If you don't have the ``gettext`` utilities installed, ``make-messages.py``
-will create empty files. If that's the case, either install the ``gettext``
-utilities or just copy the English message file
-(``conf/locale/en/LC_MESSAGES/django.po``) and use it as a starting point; it's
-just an empty translation file.
-
-Once you've created the ``.po`` file, edit the 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. Then, proceed to write your
-translations.
-
-The language code for storage is in locale format -- so it's ``pt_BR`` for
-Brazilian and ``de_AT`` for Austrian German.
-
-Every message in the message file is in the same format:
-
-    * One line is the msgid. This is the actual string in the source. Don't
-      change it.
-    * The other line is msgstr. This is the translation. It starts out empty.
-      You change it.
-
-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!
-
-Compiling message files
------------------------
-
-After you create your message file, you'll need to transform it into a more
-efficient form to be read by ``gettext``. Do this with the
-``compile-messages.py`` utility. This tool runs over all available ``.po``
-files and creates ``.mo`` files. Run it like this::
-
-   bin/compile-messages.py
-
-That's it. You made your first translation. Now, if you configure your browser
-to request your language, Django apps will use your language preference.
-
-Another thing: Please submit the name of your newly-created language in that
-native language, so we can add it to the global list of available languages
-that is mirrored in ``settings.LANGUAGES`` (and the ``LANGUAGES`` template
-variable).
-
-Using translations in your own projects
-=======================================
-
-Of course, your own projects should make use of translations. Django makes this
-simple, because it looks for message files in several locations.
-
-Django looks for translations by following this algorithm:
@@ -380 +485 @@
-
-This way, you can write applications that include their own translations, and
- if you want to do that.
-
-translations into one big project 
+. Or, you can just build
+
+
-
-All message file repositories are structured the same way. They are:
@@ -388 +493 @@
-    * ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
-    * ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
-a
+A
-      searched in that order for ``<language>/LC_MESSAGES/django.(po|mo)``
-    * ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
@@ -407 +512 @@
-be used in other projects, you might want to use app-specific translations.
-But using app-specific translations and project translations could produce
- directories
-
-
+
+
+project 
-
-The easiest way out is to store applications that are not part of the project
@@ -425 +530 @@
-    * The string domain is always ``django``. The string domain is used to
-      differentiate between different programs that store their data in a
-
+-
-      case, there are Django-specific locale libraries, so the domain itself
-      isn't used. We could store app message files with different names and put