/docs/topics/i18n/deployment.txt
Plain Text | 208 lines | 158 code | 50 blank | 0 comment | 0 complexity | 2e091f445b1e3a2e1d7399ceb3da4407 MD5 | raw file
Possible License(s): BSD-3-Clause
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.