Ticket #11714: i18n-docs.diff

docs/topics/i18n.txt

@@ -859 +859 @@
 strings that are connected to your explicit project and not strings that are
 distributed independently.
 
+Using translations outside views and templates
+==============================================
+
+While Django provides 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 appropriate translation catalog exists, of
+course). You can load translation catalog, activate it and translate text to
+language of your choice, but remember to switch back to original language, as
+activating translation catalog is done in 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 argument 'de' will give you ``"wilkommen"``,
+regardless of :setting:`LANGUAGE_CODE` and language set by middleware.
+
+Function of particular interest are ``django.utils.translation.get_language()``
+which returns language used in current thread, and
+``django.utils.translation.activate()`` which activates translation catalog for
+current thread. Other useful function is
+``django.utils.translation.check_for_language()`` checks if language is
+supported by Django.
+
 The ``set_language`` redirect view
 ==================================