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