Ticket #5495: i18n.txt.rev6292.organization.diff
| File i18n.txt.rev6292.organization.diff, 9.2 KB (added by , 17 years ago) |
|---|
-
docs/i18n.txt
27 27 * It uses these hooks to translate Web apps for particular users according 28 28 to their language preferences. 29 29 30 How to internationalize your app: in three steps 31 ------------------------------------------------ 30 If you don't need internationalization in your app 31 ================================================== 32 32 33 1. Embed translation strings in your Python code and templates.34 2. Get translations for those strings, in whichever languages you want to35 support.36 3. Activate the locale middleware in your Django settings.37 38 .. admonition:: Behind the scenes39 40 Django's translation machinery uses the standard ``gettext`` module that41 comes with Python.42 43 If you don't need internationalization44 ======================================45 46 33 Django's internationalization hooks are on by default, and that means there's a 47 34 bit of i18n-related overhead in certain places of the framework. If you don't 48 35 use internationalization, you should take the two seconds to set … … 55 42 56 43 .. _documentation for USE_I18N: ../settings/#use-i18n 57 44 58 How to specify translation strings59 ================================== 45 If you do need internationalization: three steps 46 ================================================ 60 47 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 58 1. How to specify translation strings 59 ===================================== 60 61 61 Translation strings specify "This text should be translated." These strings can 62 62 appear in your Python code and templates. It's your responsibility to mark 63 63 translatable strings; the system can only translate strings it knows about. … … 295 295 .. _Django templates: ../templates_python/ 296 296 297 297 Working with lazy translation objects 298 ===================================== 298 ------------------------------------- 299 299 300 300 Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models 301 301 and utility functions is a common operation. When you're working with these … … 305 305 couple of helper functions. 306 306 307 307 Joining strings: string_concat() 308 -------------------------------- 308 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 309 309 310 310 Standard Python string joins (``''.join([...])``) will not work on lists 311 311 containing lazy translation objects. Instead, you can use … … 324 324 rendering time). 325 325 326 326 The allow_lazy() decorator 327 -------------------------- 327 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 328 328 329 329 Django offers many utility functions (particularly in ``django.utils``) that 330 330 take a string as their first argument and do something to that string. These … … 359 359 input is a proper string, then add support for lazy translation objects at the 360 360 end. 361 361 362 How to create language files363 ============================ 362 2. How to create language files 363 =============================== 364 364 365 365 Once you've tagged your strings for later translation, you need to write (or 366 366 obtain) the language translations themselves. Here's how that works. … … 393 393 394 394 ...where ``de`` is the language code for the message file you want to create. 395 395 The language code, in this case, is in locale format. For example, it's 396 ``pt_BR`` for Brazilian Portug ese and ``de_AT`` for Austrian German.396 ``pt_BR`` for Brazilian Portuguese and ``de_AT`` for Austrian German. 397 397 398 398 The script should be run from one of three places: 399 399 … … 490 490 491 491 .. _Submitting and maintaining translations: ../contributing/ 492 492 493 How Django discovers language preference494 ======================================== 493 3. How Django discovers language preference 494 =========================================== 495 495 496 496 Once you've prepared your translations -- or, if you just want to use the 497 497 translations that come with Django -- you'll just need to activate translation … … 546 546 Notes: 547 547 548 548 * In each of these places, the language preference is expected to be in the 549 standard language format, as a string. For example, Brazilian Portug ese549 standard language format, as a string. For example, Brazilian Portuguese 550 550 is ``pt-br``. 551 551 * If a base language is available but the sublanguage specified is not, 552 552 Django uses the base language. For example, if a user specifies ``de-at`` … … 629 629 .. _session: ../sessions/ 630 630 .. _request object: ../request_response/#httprequest-objects 631 631 632 The ``set_language`` redirect view633 ==================================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 view646 saves the language choice in the user's session. Otherwise, it saves the647 language choice in a ``django_language`` cookie.648 649 After setting the language choice, Django redirects the user, following this650 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 the654 ``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 670 632 Using translations in your own projects 671 633 ======================================= 672 634 … … 728 690 connected to your explicit project and not strings that are distributed 729 691 independently. 730 692 693 The ``set_language`` redirect view 694 ================================== 695 696 As a convenience, Django comes with a view, ``django.views.i18n.set_language``, 697 that sets a user's language preference and redirects back to the previous page. 698 699 Activate 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 705 The view expects to be called via the ``POST`` method, with a ``language`` 706 parameter set in request. If session support is enabled, the view 707 saves the language choice in the user's session. Otherwise, it saves the 708 language choice in a ``django_language`` cookie. 709 710 After setting the language choice, Django redirects the user, following this 711 algorithm: 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 719 Here'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 731 731 Translations and JavaScript 732 732 =========================== 733 733 … … 827 827 After updating translation catalogs, just run ``compile-messages.py`` the same 828 828 way as you do with normal Django translation catalogs. 829 829 830 Special ities of Django translation830 Specialties of Django translation 831 831 ================================== 832 832 833 If you know ``gettext``, you might note these special ities in the way Django833 If you know ``gettext``, you might note these specialties in the way Django 834 834 does translation: 835 835 836 * The string domain is ``django`` or ``djangojs``. Th estring domain is836 * The string domain is ``django`` or ``djangojs``. This string domain is 837 837 used to differentiate between different programs that store their data 838 838 in a common message-file library (usually ``/usr/share/locale/``). The 839 839 ``django`` domain is used for python and template translation strings … … 841 841 domain is only used for JavaScript translation catalogs to make sure 842 842 that those are as small as possible. 843 843 * Django doesn't use ``xgettext`` alone. It uses Python wrappers around 844 ``xgettext`` and ``msgfmt``. Th at's mostly for convenience.844 ``xgettext`` and ``msgfmt``. This is mostly for convenience.