Fixed #10078 - Document use of locales in management commands. Thanks gregoire for the suggestion and ramiro for the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15141 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 49 insertions, 0 deletions

diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt
index 1fa3ad311a..1a8ba63a24 100644
--- a/docs/howto/custom-management-commands.txt
+++ b/docs/howto/custom-management-commands.txt
@@ -98,6 +98,55 @@ In addition to being able to add custom command line options, all
 :doc:`management commands</ref/django-admin>` can accept some
 default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.
 
+.. admonition:: Management commands and locales
+
+    The :meth:`BaseCommand.execute` method sets the hardcoded ``en-us`` locale
+    because the commands shipped with Django perform several tasks
+    (for example, user-visible content and database population) that require
+    a system-neutral string language (for which we use ``en-us``).
+
+    If your custom management command uses another locale, you should manually
+    activate and deactivate it in your :meth:`~BaseCommand.handle` or
+    :meth:`~NoArgsCommand.handle_noargs` method using the functions provided by
+    the I18N support code:
+
+    .. code-block:: python
+
+        from django.core.management.base import BaseCommand, CommandError
+        from django.utils import translation
+
+        class Command(BaseCommand):
+            ...
+            self.can_import_settings = True
+
+            def handle(self, *args, **options):
+
+                # Activate a fixed locale, e.g. Russian
+                translation.activate('ru')
+
+                # Or you can activate the LANGUAGE_CODE
+                # chosen in the settings:
+                #
+                #from django.conf import settings
+                #translation.activate(settings.LANGUAGE_CODE)
+
+                # Your command logic here
+                # ...
+
+                translation.deactivate()
+
+    Take into account though, that system management commands typically have to
+    be very careful about running in non-uniform locales, so:
+
+    * Make sure the :setting:`USE_I18N` setting is always ``True`` when running
+      the command (this is one good example of the potential problems stemming
+      from a dynamic runtime environment that Django commands avoid offhand by
+      always using a fixed locale).
+
+    * Review the code of your command and the code it calls for behavioral
+      differences when locales are changed and evaluate its impact on
+      predictable behavior of your command.
+
 Command objects
 ===============