diff -r 5ff1fc726848 -r c6bca38c1cbf parts/django/docs/howto/i18n.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/parts/django/docs/howto/i18n.txt Sat Jan 08 11:20:57 2011 +0530 @@ -0,0 +1,103 @@ +.. _using-translations-in-your-own-projects: + +=============================================== +Using internationalization in your own projects +=============================================== + +At runtime, Django looks for translations by following this algorithm: + + * First, it looks for a ``locale`` directory in the directory containing + your settings file. + * Second, it looks for a ``locale`` directory in the project directory. + * Third, it looks for a ``locale`` directory in each of the installed apps. + It does this in the reverse order of INSTALLED_APPS + * Finally, it checks the Django-provided base translation in + ``django/conf/locale``. + +In all cases the name of the directory containing the translation is expected to +be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``, +etc. + +This way, you can write applications that include their own translations, and +you can override base translations in your project path. Or, you can just build +a big project out of several apps and put all translations into one big project +message file. The choice is yours. + +.. note:: + + If you're using manually configured settings, as described in + :ref:`settings-without-django-settings-module`, the ``locale`` directory in + the project directory will not be examined, since Django loses the ability + to work out the location of the project directory. (Django normally uses the + location of the settings file to determine this, and a settings file doesn't + exist if you're manually configuring your settings.) + +All message file repositories are structured the same way. They are: + + * ``$APPPATH/locale//LC_MESSAGES/django.(po|mo)`` + * ``$PROJECTPATH/locale//LC_MESSAGES/django.(po|mo)`` + * All paths listed in ``LOCALE_PATHS`` in your settings file are + searched in that order for ``/LC_MESSAGES/django.(po|mo)`` + * ``$PYTHONPATH/django/conf/locale//LC_MESSAGES/django.(po|mo)`` + +To create message files, you use the :djadmin:`django-admin.py makemessages ` +tool. You only need to be in the same directory where the ``locale/`` directory +is located. And you use :djadmin:`django-admin.py compilemessages ` +to produce the binary ``.mo`` files that are used by ``gettext``. Read the +:doc:`/topics/i18n/localization` document for more details. + +You can also run ``django-admin.py compilemessages --settings=path.to.settings`` +to make the compiler process all the directories in your :setting:`LOCALE_PATHS` +setting. + +Application message files are a bit complicated to discover -- they need the +:class:`~django.middleware.locale.LocaleMiddleware`. If you don't use the +middleware, only the Django message files and project message files will be +installed and available at runtime. + +Finally, you should give some thought to the structure of your translation +files. If your applications need to be delivered to other users and will +be used in other projects, you might want to use app-specific translations. +But using app-specific translations and project translations could produce +weird problems with ``makemessages``: It will traverse all directories below +the current path and so might put message IDs into the project message file +that are already in application message files. + +The easiest way out is to store applications that are not part of the project +(and so carry their own translations) outside the project tree. That way, +``django-admin.py makemessages`` on the project level will only translate +strings that are connected to your explicit project and not strings that are +distributed independently. + +Using translations outside views and templates +============================================== + +While Django provides a rich set of i18n tools for use in views and templates, +it does not restrict the usage to Django-specific code. The Django translation +mechanisms can be used to translate arbitrary texts to any language that is +supported by Django (as long as an appropriate translation catalog exists, of +course). You can load a translation catalog, activate it and translate text to +language of your choice, but remember to switch back to original language, as +activating a translation catalog is done on per-thread basis and such change +will affect code running in the same thread. + +For example:: + + from django.utils import translation + def welcome_translated(language): + cur_language = translation.get_language() + try: + translation.activate(language) + text = translation.ugettext('welcome') + finally: + translation.activate(cur_language) + return text + +Calling this function with the value 'de' will give you ``"Willkommen"``, +regardless of :setting:`LANGUAGE_CODE` and language set by middleware. + +Functions of particular interest are ``django.utils.translation.get_language()`` +which returns the language used in the current thread, +``django.utils.translation.activate()`` which activates a translation catalog +for the current thread, and ``django.utils.translation.check_for_language()`` +which checks if the given language is supported by Django.