Ticket #10078: 10078.diff

docs/howto/custom-management-commands.txt

@@ -98 +98 @@
 :doc:`management commands</ref/django-admin>` can accept some
 default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.
 
+.. admonition:: Management commands and locales
+
+    Django :class:`BaseCommand` :meth:`~BaseCommand.execute` method sets the
+    hardcoded ``en-us`` locale, the reason for this is that the commands shipped
+    with Django performs several tasks that really require a system-neutral
+    string language (for which we use ``en-us``), user-visible content and
+    database population being two examples.
+
+    If, for any reason, you need that you 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):
+
+                # Activte 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 in 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 dymamic runtime enviroment that Django commands avoid offhand by
+      always using a fixed locale).
+
+    * Review the code of you command and the code it calls for behavioral
+      differences it might show when locales are changed and evaluate its impact
+      on predictable behavior of your command.
+
 Command objects
 ===============