From 0d4726f5189ff2d138435fed223b91e6af167777 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Sun, 21 Feb 2010 23:44:05 +0000 Subject: [PATCH] Fixed #11714 - Document a few of the i18n function that can be used outside views and templates. Thanks, Jarek Zgoda and Ramiro Morales. git-svn-id: http://code.djangoproject.com/svn/django/trunk@12473 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/howto/i18n.txt | 33 +++++++++++++++++++++++++++++++ docs/topics/i18n/index.txt | 4 ++-- docs/topics/i18n/localization.txt | 7 +++---- 3 files changed, 38 insertions(+), 6 deletions(-) diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index 722ab7ba90..853162aa70 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -70,3 +70,36 @@ The easiest way out is to store applications that are not part of the project ``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. diff --git a/docs/topics/i18n/index.txt b/docs/topics/i18n/index.txt index e3db1a2d52..e39a75067a 100644 --- a/docs/topics/i18n/index.txt +++ b/docs/topics/i18n/index.txt @@ -18,11 +18,11 @@ Essentially, Django does two things: to their language preferences. The complete process can be seen as divided in three stages. It is also possible -to identify an identical number of roles with very well defined responsabilities +to identify an identical number of roles with very well defined responsibilities associated with each of these tasks (although it's perfectly normal if you find yourself performing more than one of these roles): - * For applicacion authors wishing to make sure their Django apps can be + * For application authors wishing to make sure their Django apps can be used in different locales: :ref:`topics-i18n-internationalization`. * For translators wanting to translate Django apps: :ref:`topics-i18n-localization`. * For system administrators/final users setting up internationalized apps or diff --git a/docs/topics/i18n/localization.txt b/docs/topics/i18n/localization.txt index 2cd3eb1af3..5f7c6254d8 100644 --- a/docs/topics/i18n/localization.txt +++ b/docs/topics/i18n/localization.txt @@ -237,8 +237,7 @@ test or compile a changed message file, you will need the ``gettext`` utilities: .. _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. Some version 0.14.4 binaries -have been found to not support this command. Do not attempt to use Django +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". @@ -248,7 +247,7 @@ translation utilities with a ``gettext`` package if the command ``xgettext Format localization =================== -Django's formatting system is disabled by default. To enable it, it's necessay +Django's formatting system is disabled by default. To enable it, it's necessary to set :setting:`USE_L10N = True ` in your settings file. When using Django's formatting system, dates and numbers on templates will be @@ -271,7 +270,7 @@ 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 the path (in the format ``'foo.bar.baz``) where format files +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