Mercurial > babel > mirror
comparison doc/catalogs.txt @ 2:20896f1e91c6 trunk
Forgot to check in the doc directory.
| author | cmlenz |
|---|---|
| date | Wed, 30 May 2007 07:37:26 +0000 |
| parents | |
| children | 0739bc8e7210 |
comparison
equal
deleted
inserted
replaced
| 1:7870274479f5 | 2:20896f1e91c6 |
|---|---|
| 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')) |