|
4
|
1 .. -*- mode: rst; encoding: utf-8 -*-
|
|
|
2
|
|
|
3 =============================
|
|
|
4 Working with Message Catalogs
|
|
|
5 =============================
|
|
|
6
|
|
|
7 .. contents:: Contents
|
|
|
8 :depth: 2
|
|
|
9 .. sectnum::
|
|
|
10
|
|
|
11
|
|
|
12 Introduction
|
|
|
13 ============
|
|
|
14
|
|
|
15 The ``gettext`` translation system enables you to mark any strings used in your
|
|
|
16 application as subject to localization, by wrapping them in functions such as
|
|
|
17 ``gettext(str)`` and ``ngettext(singular, plural, num)``. For brevity, the
|
|
42
|
18 ``gettext`` function is often aliased to ``_(str)``, so you can write:
|
|
|
19
|
|
|
20 .. code-block:: python
|
|
4
|
21
|
|
|
22 print _("Hello")
|
|
|
23
|
|
42
|
24 instead of just:
|
|
|
25
|
|
|
26 .. code-block:: python
|
|
4
|
27
|
|
|
28 print "Hello"
|
|
|
29
|
|
|
30 to make the string "Hello" localizable.
|
|
|
31
|
|
|
32 Message catalogs are collections of translations for such localizable messages
|
|
|
33 used in an application. They are commonly stored in PO (Portable Object) and MO
|
|
|
34 (Machine Object) files, the formats of which are defined by the GNU `gettext`_
|
|
|
35 tools and the GNU `translation project`_.
|
|
|
36
|
|
|
37 .. _`gettext`: http://www.gnu.org/software/gettext/
|
|
|
38 .. _`translation project`: http://sourceforge.net/projects/translation
|
|
|
39
|
|
|
40 The general procedure for building message catalogs looks something like this:
|
|
|
41
|
|
|
42 * use a tool (such as ``xgettext``) to extract localizable strings from the
|
|
|
43 code base and write them to a POT (PO Template) file.
|
|
|
44 * make a copy of the POT file for a specific locale (for example, "en_US")
|
|
|
45 and start translating the messages
|
|
|
46 * use a tool such as ``msgfmt`` to compile the locale PO file into an binary
|
|
|
47 MO file
|
|
|
48 * later, when code changes make it necessary to update the translations, you
|
|
|
49 regenerate the POT file and merge the changes into the various
|
|
|
50 locale-specific PO files, for example using ``msgmerge``
|
|
|
51
|
|
|
52 Python provides the `gettext module`_ as part of the standard library, which
|
|
|
53 enables applications to work with appropriately generated MO files.
|
|
|
54
|
|
|
55 .. _`gettext module`: http://docs.python.org/lib/module-gettext.html
|
|
|
56
|
|
|
57 As ``gettext`` provides a solid and well supported foundation for translating
|
|
|
58 application messages, Babel does not reinvent the wheel, but rather reuses this
|
|
|
59 infrastructure, and makes it easier to build message catalogs for Python
|
|
|
60 applications.
|
|
|
61
|
|
|
62
|
|
|
63 Message Extraction
|
|
|
64 ==================
|
|
|
65
|
|
|
66 Babel provides functionality similar to that of the ``xgettext`` program,
|
|
|
67 except that only extraction from Python source files is built-in, while support
|
|
|
68 for other file formats can be added using a simple extension mechanism.
|
|
|
69
|
|
|
70 (TODO: more)
|
|
|
71
|
|
|
72
|
|
|
73 --------------------------
|
|
|
74 Writing Extraction Methods
|
|
|
75 --------------------------
|
|
|
76
|
|
|
77 (TODO: write)
|
|
|
78
|
|
|
79 ---------------------
|
|
|
80 ``setup.py`` Commands
|
|
|
81 ---------------------
|
|
|
82
|
|
|
83 (TODO: overview)
|
|
|
84
|
|
|
85 See `Distutils/Setuptools Integration <setup.html>`_ for more information.
|
|
|
86
|
|
|
87 -------------------
|
|
|
88 Command-line script
|
|
|
89 -------------------
|
|
|
90
|
|
|
91 (TODO: overview)
|
|
|
92
|
|
|
93 See `Command-Line Interface <cmdline.html>`_ for more information.
|
|
|
94
|
|
|
95
|
|
|
96 Extended ``Translations`` Class
|
|
|
97 ===============================
|
|
|
98
|
|
|
99 Many web-based applications are composed of a variety of different components
|
|
|
100 (possibly using some kind of plugin system), and some of those components may
|
|
|
101 provide their own message catalogs that need to be integrated into the larger
|
|
|
102 system.
|
|
|
103
|
|
|
104 To support this usage pattern, Babel provides a ``Translations`` class that is
|
|
|
105 derived from the ``GNUTranslations`` class in the ``gettext`` module. This
|
|
|
106 class adds a ``merge()`` method that takes another ``Translations`` instance,
|
|
|
107 and merges its contents into the catalog::
|
|
|
108
|
|
42
|
109 .. code-block:: python
|
|
|
110
|
|
4
|
111 translations = Translations.load('main')
|
|
|
112 translations.merge(Translations.load('plugin1'))
|
