|
1 .. _using-translations-in-your-own-projects: |
|
2 |
|
3 =============================================== |
|
4 Using internationalization in your own projects |
|
5 =============================================== |
|
6 |
|
7 At runtime, Django looks for translations by following this algorithm: |
|
8 |
|
9 * First, it looks for a ``locale`` directory in the directory containing |
|
10 your settings file. |
|
11 * Second, it looks for a ``locale`` directory in the project directory. |
|
12 * Third, it looks for a ``locale`` directory in each of the installed apps. |
|
13 It does this in the reverse order of INSTALLED_APPS |
|
14 * Finally, it checks the Django-provided base translation in |
|
15 ``django/conf/locale``. |
|
16 |
|
17 In all cases the name of the directory containing the translation is expected to |
|
18 be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``, |
|
19 etc. |
|
20 |
|
21 This way, you can write applications that include their own translations, and |
|
22 you can override base translations in your project path. Or, you can just build |
|
23 a big project out of several apps and put all translations into one big project |
|
24 message file. The choice is yours. |
|
25 |
|
26 .. note:: |
|
27 |
|
28 If you're using manually configured settings, as described in |
|
29 :ref:`settings-without-django-settings-module`, the ``locale`` directory in |
|
30 the project directory will not be examined, since Django loses the ability |
|
31 to work out the location of the project directory. (Django normally uses the |
|
32 location of the settings file to determine this, and a settings file doesn't |
|
33 exist if you're manually configuring your settings.) |
|
34 |
|
35 All message file repositories are structured the same way. They are: |
|
36 |
|
37 * ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)`` |
|
38 * ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)`` |
|
39 * All paths listed in ``LOCALE_PATHS`` in your settings file are |
|
40 searched in that order for ``<language>/LC_MESSAGES/django.(po|mo)`` |
|
41 * ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)`` |
|
42 |
|
43 To create message files, you use the :djadmin:`django-admin.py makemessages <makemessages>` |
|
44 tool. You only need to be in the same directory where the ``locale/`` directory |
|
45 is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>` |
|
46 to produce the binary ``.mo`` files that are used by ``gettext``. Read the |
|
47 :doc:`/topics/i18n/localization` document for more details. |
|
48 |
|
49 You can also run ``django-admin.py compilemessages --settings=path.to.settings`` |
|
50 to make the compiler process all the directories in your :setting:`LOCALE_PATHS` |
|
51 setting. |
|
52 |
|
53 Application message files are a bit complicated to discover -- they need the |
|
54 :class:`~django.middleware.locale.LocaleMiddleware`. If you don't use the |
|
55 middleware, only the Django message files and project message files will be |
|
56 installed and available at runtime. |
|
57 |
|
58 Finally, you should give some thought to the structure of your translation |
|
59 files. If your applications need to be delivered to other users and will |
|
60 be used in other projects, you might want to use app-specific translations. |
|
61 But using app-specific translations and project translations could produce |
|
62 weird problems with ``makemessages``: It will traverse all directories below |
|
63 the current path and so might put message IDs into the project message file |
|
64 that are already in application message files. |
|
65 |
|
66 The easiest way out is to store applications that are not part of the project |
|
67 (and so carry their own translations) outside the project tree. That way, |
|
68 ``django-admin.py makemessages`` on the project level will only translate |
|
69 strings that are connected to your explicit project and not strings that are |
|
70 distributed independently. |
|
71 |
|
72 Using translations outside views and templates |
|
73 ============================================== |
|
74 |
|
75 While Django provides a rich set of i18n tools for use in views and templates, |
|
76 it does not restrict the usage to Django-specific code. The Django translation |
|
77 mechanisms can be used to translate arbitrary texts to any language that is |
|
78 supported by Django (as long as an appropriate translation catalog exists, of |
|
79 course). You can load a translation catalog, activate it and translate text to |
|
80 language of your choice, but remember to switch back to original language, as |
|
81 activating a translation catalog is done on per-thread basis and such change |
|
82 will affect code running in the same thread. |
|
83 |
|
84 For example:: |
|
85 |
|
86 from django.utils import translation |
|
87 def welcome_translated(language): |
|
88 cur_language = translation.get_language() |
|
89 try: |
|
90 translation.activate(language) |
|
91 text = translation.ugettext('welcome') |
|
92 finally: |
|
93 translation.activate(cur_language) |
|
94 return text |
|
95 |
|
96 Calling this function with the value 'de' will give you ``"Willkommen"``, |
|
97 regardless of :setting:`LANGUAGE_CODE` and language set by middleware. |
|
98 |
|
99 Functions of particular interest are ``django.utils.translation.get_language()`` |
|
100 which returns the language used in the current thread, |
|
101 ``django.utils.translation.activate()`` which activates a translation catalog |
|
102 for the current thread, and ``django.utils.translation.check_for_language()`` |
|
103 which checks if the given language is supported by Django. |