/docs/topics/i18n/deployment.txt

  1==========================
  2Deployment of translations
  3==========================
  4
  5If you don't need internationalization
  6======================================
  7
  8Django's internationalization hooks are on by default, and that means there's a
  9bit of i18n-related overhead in certain places of the framework. If you don't
 10use internationalization, you should take the two seconds to set
 11:setting:`USE_I18N = False <USE_I18N>` in your settings file. If
 12:setting:`USE_I18N` is set to ``False``, then Django will make some
 13optimizations so as not to load the internationalization machinery.
 14
 15You'll probably also want to remove ``'django.core.context_processors.i18n'``
 16from your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
 17
 18.. note::
 19
 20    There is also an independent but related :setting:`USE_L10N` setting that
 21    controls if Django should implement format localization.
 22
 23    If :setting:`USE_L10N` is set to ``True``, Django will handle numbers times,
 24    and dates in the format of the current locale. That includes representation
 25    of these field types on templates and allowed input formats for dates,
 26    times on model forms.
 27
 28    See :ref:`format-localization` for more details.
 29
 30If you do need internationalization
 31===================================
 32
 33.. _how-django-discovers-language-preference:
 34
 35How Django discovers language preference
 36----------------------------------------
 37
 38Once you've prepared your translations -- or, if you just want to use the
 39translations that come with Django -- you'll just need to activate translation
 40for your app.
 41
 42Behind the scenes, Django has a very flexible model of deciding which language
 43should be used -- installation-wide, for a particular user, or both.
 44
 45To set an installation-wide language preference, set :setting:`LANGUAGE_CODE`.
 46Django uses this language as the default translation -- the final attempt if no
 47other translator finds a translation.
 48
 49If all you want to do is run Django with your native language, and a language
 50file is available for it, all you need to do is set :setting:`LANGUAGE_CODE`.
 51
 52If you want to let each individual user specify which language he or she
 53prefers, use ``LocaleMiddleware``. ``LocaleMiddleware`` enables language
 54selection based on data from the request. It customizes content for each user.
 55
 56To use ``LocaleMiddleware``, add ``'django.middleware.locale.LocaleMiddleware'``
 57to your :setting:`MIDDLEWARE_CLASSES` setting. Because middleware order
 58matters, you should follow these guidelines:
 59
 60    * Make sure it's one of the first middlewares installed.
 61    * It should come after ``SessionMiddleware``, because ``LocaleMiddleware``
 62      makes use of session data.
 63    * If you use ``CacheMiddleware``, put ``LocaleMiddleware`` after it.
 64
 65For example, your :setting:`MIDDLEWARE_CLASSES` might look like this::
 66
 67    MIDDLEWARE_CLASSES = (
 68       'django.contrib.sessions.middleware.SessionMiddleware',
 69       'django.middleware.locale.LocaleMiddleware',
 70       'django.middleware.common.CommonMiddleware',
 71    )
 72
 73(For more on middleware, see the :doc:`middleware documentation
 74</topics/http/middleware>`.)
 75
 76``LocaleMiddleware`` tries to determine the user's language preference by
 77following this algorithm:
 78
 79    * First, it looks for a ``django_language`` key in the current user's
 80      session.
 81
 82    * Failing that, it looks for a cookie.
 83
 84      The name of the cookie used is set by the :setting:`LANGUAGE_COOKIE_NAME`
 85      setting. (The default name is ``django_language``.)
 86
 87    * Failing that, it looks at the ``Accept-Language`` HTTP header. This
 88      header is sent by your browser and tells the server which language(s) you
 89      prefer, in order by priority. Django tries each language in the header
 90      until it finds one with available translations.
 91
 92    * Failing that, it uses the global :setting:`LANGUAGE_CODE` setting.
 93
 94.. _locale-middleware-notes:
 95
 96Notes:
 97
 98    * In each of these places, the language preference is expected to be in the
 99      standard :term:`language format<language code>`, as a string. For example,
100      Brazilian Portuguese is ``pt-br``.
101
102    * If a base language is available but the sublanguage specified is not,
103      Django uses the base language. For example, if a user specifies ``de-at``
104      (Austrian German) but Django only has ``de`` available, Django uses
105      ``de``.
106
107    * Only languages listed in the :setting:`LANGUAGES` setting can be selected.
108      If you want to restrict the language selection to a subset of provided
109      languages (because your application doesn't provide all those languages),
110      set :setting:`LANGUAGES` to a list of languages. For example::
111
112          LANGUAGES = (
113            ('de', _('German')),
114            ('en', _('English')),
115          )
116
117      This example restricts languages that are available for automatic
118      selection to German and English (and any sublanguage, like de-ch or
119      en-us).
120
121    * If you define a custom :setting:`LANGUAGES` setting, as explained in the
122      previous bullet, it's OK to mark the languages as translation strings
123      -- but use a "dummy" ``ugettext()`` function, not the one in
124      ``django.utils.translation``. You should *never* import
125      ``django.utils.translation`` from within your settings file, because that
126      module in itself depends on the settings, and that would cause a circular
127      import.
128
129      The solution is to use a "dummy" ``ugettext()`` function. Here's a sample
130      settings file::
131
132          ugettext = lambda s: s
133
134          LANGUAGES = (
135              ('de', ugettext('German')),
136              ('en', ugettext('English')),
137          )
138
139      With this arrangement, ``django-admin.py makemessages`` will still find
140      and mark these strings for translation, but the translation won't happen
141      at runtime -- so you'll have to remember to wrap the languages in the
142      *real* ``ugettext()`` in any code that uses :setting:`LANGUAGES` at
143      runtime.
144
145    * The ``LocaleMiddleware`` can only select languages for which there is a
146      Django-provided base translation. If you want to provide translations
147      for your application that aren't already in the set of translations
148      in Django's source tree, you'll want to provide at least a basic
149      one as described in the :ref:`Locale restrictions<locale-restrictions>`
150      note.
151
152Once ``LocaleMiddleware`` determines the user's preference, it makes this
153preference available as ``request.LANGUAGE_CODE`` for each
154:class:`~django.http.HttpRequest`. Feel free to read this value in your view
155code. Here's a simple example::
156
157    def hello_world(request, count):
158        if request.LANGUAGE_CODE == 'de-at':
159            return HttpResponse("You prefer to read Austrian German.")
160        else:
161            return HttpResponse("You prefer to read another language.")
162
163Note that, with static (middleware-less) translation, the language is in
164``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's
165in ``request.LANGUAGE_CODE``.
166
167.. _settings file: ../settings/
168.. _middleware documentation: ../middleware/
169.. _session: ../sessions/
170.. _request object: ../request_response/#httprequest-objects
171
172How Django discovers translations
173---------------------------------
174
175As described in :ref:`using-translations-in-your-own-projects`, Django looks for
176translations by following this algorithm regarding the order in which it
177examines the different file paths to load the compiled :term:`message files
178<message file>` (``.mo``) and the precedence of multiple translations for the
179same literal:
180
181    1. The directories listed in :setting:`LOCALE_PATHS` have the highest
182       precedence, with the ones appearing first having higher precedence than
183       the ones appearing later.
184    2. Then, it looks for and uses if it exists a ``locale`` directory in each
185       of the installed apps listed in :setting:`INSTALLED_APPS`.  The ones
186       appearing first have higher precedence than the ones appearing later.
187    3. Then, it looks for a ``locale`` directory in the project directory, or
188       more accurately, in the directory containing your settings file.
189    4. Finally, the Django-provided base translation in ``django/conf/locale``
190       is used as a fallback.
191
192.. deprecated:: 1.3
193    Lookup in the ``locale`` subdirectory of the directory containing your
194    settings file (item 3 above) is deprecated since the 1.3 release and will be
195    removed in Django 1.5. You can use the :setting:`LOCALE_PATHS` setting
196    instead, by listing the absolute filesystem path of such ``locale``
197    directory in the setting value.
198
199.. seealso::
200
201    The translations for literals included in JavaScript assets are looked up
202    following a similar but not identical algorithm. See the
203    :ref:`javascript_catalog view documentation <javascript_catalog-view>` for
204    more details.
205
206In all cases the name of the directory containing the translation is expected to
207be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``,
208etc.