Ticket #5495: i18n.txt.rev6292.organization.diff

File i18n.txt.rev6292.organization.diff, 9.2 KB (added by Axis_of_Entropy, 8 years ago)

patch to docs/i18n.txt - organization, spelling, grammar

  • docs/i18n.txt

     
    2727    * It uses these hooks to translate Web apps for particular users according
    2828      to their language preferences.
    2929
    30 How to internationalize your app: in three steps
    31 ------------------------------------------------
     30If you don't need internationalization in your app
     31==================================================
    3232
    33     1. Embed translation strings in your Python code and templates.
    34     2. Get translations for those strings, in whichever languages you want to
    35        support.
    36     3. Activate the locale middleware in your Django settings.
    37 
    38 .. admonition:: Behind the scenes
    39 
    40     Django's translation machinery uses the standard ``gettext`` module that
    41     comes with Python.
    42 
    43 If you don't need internationalization
    44 ======================================
    45 
    4633Django's internationalization hooks are on by default, and that means there's a
    4734bit of i18n-related overhead in certain places of the framework. If you don't
    4835use internationalization, you should take the two seconds to set
     
    5542
    5643.. _documentation for USE_I18N: ../settings/#use-i18n
    5744
    58 How to specify translation strings
    59 ==================================
     45If you do need internationalization: three steps
     46================================================
    6047
     48    1. Embed translation strings in your Python code and templates.
     49    2. Get translations for those strings, in whichever languages you want to
     50       support.
     51    3. Activate the locale middleware in your Django settings.
     52
     53.. admonition:: Behind the scenes
     54
     55    Django's translation machinery uses the standard ``gettext`` module that
     56    comes with Python.
     57
     581. How to specify translation strings
     59=====================================
     60
    6161Translation strings specify "This text should be translated." These strings can
    6262appear in your Python code and templates. It's your responsibility to mark
    6363translatable strings; the system can only translate strings it knows about.
     
    295295.. _Django templates: ../templates_python/
    296296
    297297Working with lazy translation objects
    298 =====================================
     298-------------------------------------
    299299
    300300Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models
    301301and utility functions is a common operation. When you're working with these
     
    305305couple of helper functions.
    306306
    307307Joining strings: string_concat()
    308 --------------------------------
     308~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    309309
    310310Standard Python string joins (``''.join([...])``) will not work on lists
    311311containing lazy translation objects. Instead, you can use
     
    324324rendering time).
    325325
    326326The allow_lazy() decorator
    327 --------------------------
     327~~~~~~~~~~~~~~~~~~~~~~~~~~
    328328
    329329Django offers many utility functions (particularly in ``django.utils``) that
    330330take a string as their first argument and do something to that string. These
     
    359359input is a proper string, then add support for lazy translation objects at the
    360360end.
    361361
    362 How to create language files
    363 ============================
     3622. How to create language files
     363===============================
    364364
    365365Once you've tagged your strings for later translation, you need to write (or
    366366obtain) the language translations themselves. Here's how that works.
     
    393393
    394394...where ``de`` is the language code for the message file you want to create.
    395395The language code, in this case, is in locale format. For example, it's
    396 ``pt_BR`` for Brazilian Portugese and ``de_AT`` for Austrian German.
     396``pt_BR`` for Brazilian Portuguese and ``de_AT`` for Austrian German.
    397397
    398398The script should be run from one of three places:
    399399
     
    490490
    491491    .. _Submitting and maintaining translations: ../contributing/
    492492
    493 How Django discovers language preference
    494 ========================================
     4933. How Django discovers language preference
     494===========================================
    495495
    496496Once you've prepared your translations -- or, if you just want to use the
    497497translations that come with Django -- you'll just need to activate translation
     
    546546Notes:
    547547
    548548    * In each of these places, the language preference is expected to be in the
    549       standard language format, as a string. For example, Brazilian Portugese
     549      standard language format, as a string. For example, Brazilian Portuguese
    550550      is ``pt-br``.
    551551    * If a base language is available but the sublanguage specified is not,
    552552      Django uses the base language. For example, if a user specifies ``de-at``
     
    629629.. _session: ../sessions/
    630630.. _request object: ../request_response/#httprequest-objects
    631631
    632 The ``set_language`` redirect view
    633 ==================================
    634 
    635 As a convenience, Django comes with a view, ``django.views.i18n.set_language``,
    636 that sets a user's language preference and redirects back to the previous page.
    637 
    638 Activate this view by adding the following line to your URLconf::
    639 
    640     (r'^i18n/', include('django.conf.urls.i18n')),
    641 
    642 (Note that this example makes the view available at ``/i18n/setlang/``.)
    643 
    644 The view expects to be called via the ``POST`` method, with a ``language``
    645 parameter set in request. If session support is enabled, the view
    646 saves the language choice in the user's session. Otherwise, it saves the
    647 language choice in a ``django_language`` cookie.
    648 
    649 After setting the language choice, Django redirects the user, following this
    650 algorithm:
    651 
    652     * Django looks for a ``next`` parameter in ``POST`` request.
    653     * If that doesn't exist, or is empty, Django tries the URL in the
    654       ``Referer`` header.
    655     * If that's empty -- say, if a user's browser suppresses that header --
    656       then the user will be redirected to ``/`` (the site root) as a fallback.
    657 
    658 Here's example HTML template code::
    659 
    660     <form action="/i18n/setlang/" method="post">
    661     <input name="next" type="hidden" value="/next/page/" />
    662     <select name="language">
    663     {% for lang in LANGUAGES %}
    664     <option value="{{ lang.0 }}">{{ lang.1 }}</option>
    665     {% endfor %}
    666     </select>
    667     <input type="submit" value="Go" />
    668     </form>
    669 
    670632Using translations in your own projects
    671633=======================================
    672634
     
    728690connected to your explicit project and not strings that are distributed
    729691independently.
    730692
     693The ``set_language`` redirect view
     694==================================
     695
     696As a convenience, Django comes with a view, ``django.views.i18n.set_language``,
     697that sets a user's language preference and redirects back to the previous page.
     698
     699Activate this view by adding the following line to your URLconf::
     700
     701    (r'^i18n/', include('django.conf.urls.i18n')),
     702
     703(Note that this example makes the view available at ``/i18n/setlang/``.)
     704
     705The view expects to be called via the ``POST`` method, with a ``language``
     706parameter set in request. If session support is enabled, the view
     707saves the language choice in the user's session. Otherwise, it saves the
     708language choice in a ``django_language`` cookie.
     709
     710After setting the language choice, Django redirects the user, following this
     711algorithm:
     712
     713    * Django looks for a ``next`` parameter in ``POST`` request.
     714    * If that doesn't exist, or is empty, Django tries the URL in the
     715      ``Referrer`` header.
     716    * If that's empty -- say, if a user's browser suppresses that header --
     717      then the user will be redirected to ``/`` (the site root) as a fallback.
     718
     719Here's example HTML template code::
     720
     721    <form action="/i18n/setlang/" method="post">
     722    <input name="next" type="hidden" value="/next/page/" />
     723    <select name="language">
     724    {% for lang in LANGUAGES %}
     725    <option value="{{ lang.0 }}">{{ lang.1 }}</option>
     726    {% endfor %}
     727    </select>
     728    <input type="submit" value="Go" />
     729    </form>
     730
    731731Translations and JavaScript
    732732===========================
    733733
     
    827827After updating translation catalogs, just run ``compile-messages.py`` the same
    828828way as you do with normal Django translation catalogs.
    829829
    830 Specialities of Django translation
     830Specialties of Django translation
    831831==================================
    832832
    833 If you know ``gettext``, you might note these specialities in the way Django
     833If you know ``gettext``, you might note these specialties in the way Django
    834834does translation:
    835835
    836     * The string domain is ``django`` or ``djangojs``. The string domain is
     836    * The string domain is ``django`` or ``djangojs``. This string domain is
    837837      used to differentiate between different programs that store their data
    838838      in a common message-file library (usually ``/usr/share/locale/``). The
    839839      ``django`` domain is used for python and template translation strings
     
    841841      domain is only used for JavaScript translation catalogs to make sure
    842842      that those are as small as possible.
    843843    * Django doesn't use ``xgettext`` alone. It uses Python wrappers around
    844       ``xgettext`` and ``msgfmt``. That's mostly for convenience.
     844      ``xgettext`` and ``msgfmt``. This is mostly for convenience.
Back to Top