Mercurial > babel > mirror

annotate doc/catalogs.txt @ 76:c659c39e0eee trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Typo on `doc/catalogs.txt`.
author palgarvio
date Fri, 08 Jun 2007 23:16:38 +0000
parents 9bc73c0bf7e5
children 85af04c72ccd
rev   line source
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
3 =============================
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
4 Working with Message Catalogs
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
5 =============================
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7 .. contents:: Contents
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 :depth: 2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 .. sectnum::
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12 Introduction
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
13 ============
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
14
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
15 The ``gettext`` translation system enables you to mark any strings used in your
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
16 application as subject to localization, by wrapping them in functions such as
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
17 ``gettext(str)`` and ``ngettext(singular, plural, num)``. For brevity, the
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
18 ``gettext`` function is often aliased to ``_(str)``, so you can write:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
19
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
20 .. code-block:: python
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
21
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
22 print _("Hello")
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
23
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
24 instead of just:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
25
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
26 .. code-block:: python
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
27
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
28 print "Hello"
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
29
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
30 to make the string "Hello" localizable.
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
31
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
32 Message catalogs are collections of translations for such localizable messages
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
33 used in an application. They are commonly stored in PO (Portable Object) and MO
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
34 (Machine Object) files, the formats of which are defined by the GNU `gettext`_
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
35 tools and the GNU `translation project`_.
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
36
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
37 .. _`gettext`: http://www.gnu.org/software/gettext/
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
38 .. _`translation project`: http://sourceforge.net/projects/translation
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
39
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
40 The general procedure for building message catalogs looks something like this:
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
41
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
42 * use a tool (such as ``xgettext``) to extract localizable strings from the
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
43 code base and write them to a POT (PO Template) file.
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
44 * make a copy of the POT file for a specific locale (for example, "en_US")
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
45 and start translating the messages
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
46 * use a tool such as ``msgfmt`` to compile the locale PO file into an binary
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
47 MO file
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
48 * later, when code changes make it necessary to update the translations, you
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
49 regenerate the POT file and merge the changes into the various
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
50 locale-specific PO files, for example using ``msgmerge``
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
51
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
52 Python provides the `gettext module`_ as part of the standard library, which
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
53 enables applications to work with appropriately generated MO files.
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
54
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
55 .. _`gettext module`: http://docs.python.org/lib/module-gettext.html
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
56
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
57 As ``gettext`` provides a solid and well supported foundation for translating
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
58 application messages, Babel does not reinvent the wheel, but rather reuses this
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
59 infrastructure, and makes it easier to build message catalogs for Python
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
60 applications.
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
61
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
62
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
63 Message Extraction
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
64 ==================
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
65
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
66 Babel provides functionality similar to that of the ``xgettext`` program,
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
67 except that only extraction from Python source files is built-in, while support
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
68 for other file formats can be added using a simple extension mechanism.
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
69
48
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
70 Unlike ``xgettext``, which is usually invoked once for every file, the routines
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
71 for message extraction in Babel operate on directories. While the per-file
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
72 approach of ``xgettext`` works nicely with projects using a ``Makefile``,
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
73 Python projects rarely use ``make``, and thus a different mechanism is needed
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
74 for extracting messages from the heterogeneous collection of source files that
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
75 many Python projects are composed of.
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
76
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
77 When message extraction is based on directories instead of individual files,
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
78 there needs to be a way to configure which files should be treated in which
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
79 manner. For example, while many projects may contain ``.html`` files, some of
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
80 those files may be static HTML files that don't contain localizable message,
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
81 while others may be `Django`_ templates, and still others may contain `Genshi`_
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
82 markup templates. Some projects may even mix HTML files for different templates
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
83 languages (for whatever reason). Therefore the way in which messages are
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
84 extracted from source files can not only depend on the file extension, but
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
85 needs to be controllable in a precise manner.
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
86
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
87 .. _`Django`: http://www.djangoproject.com/
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
88 .. _`Genshi`: http://genshi.edgewall.org/
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
89
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
90 Babel accepts a configuration file to specify this mapping of files to
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
91 extraction methods, which is described below.
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
92
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
93
48
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
94 .. _`mapping`:
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
95
48
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
96 -------------------------------------------
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
97 Extraction Method Mapping and Configuration
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
98 -------------------------------------------
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
99
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
100 The mapping of extraction methods to files in Babel is done via a configuration
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
101 file. This file maps extended glob patterns to the names of the extraction
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
102 methods, and can also set various options for each pattern (which options are
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
103 available depends on the specific extraction method).
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
104
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
105 For example, the following configuration adds extraction of messages from both
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
106 Genshi markup templates and text templates:
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
107
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
108 .. code-block:: ini
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
109
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
110 # Extraction from Python source files
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
111
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
112 [python: foobar/**.py]
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
113
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
114 # Extraction from Genshi HTML and text templates
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
115
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
116 [genshi: foobar/**/templates/**.html]
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
117 ignore_tags = script,style
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
118 include_attrs = alt title summary
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
119
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
120 [genshi: foobar/**/templates/**.txt]
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
121 template_class = genshi.template.text:TextTemplate
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
122 encoding = ISO-8819-15
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
123
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
124 The configuration file syntax is based on the format commonly found in ``.INI``
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
125 files on Windows systems, and as supported by the ``ConfigParser`` module in
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
126 the Python standard libraries. Section names (the strings enclosed in square
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
127 brackets) specify both the name of the extraction method, and the extended glob
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
128 pattern to specify the files that this extraction method should be used for,
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
129 separated by a colon. The options in the sections are passed to the extraction
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
130 method. Which options are available is specific to the extraction method used.
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
131
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
132 The extended glob patterns used in this configuration are similar to the glob
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
133 patterns provided by most shells. A single asterisk (``*``) is a wildcard for
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
134 any number of characters (except for the pathname component separator "/"),
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
135 while a question mark (``?``) only matches a single character. In addition,
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
136 two subsequent asterisk characters (``**``) can be used to make the wildcard
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
137 match any directory level, so the pattern ``**.txt`` matches any file with the
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
138 extension ``.txt`` in any directory.
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
139
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
140 Lines that start with a ``#`` or ``;`` character are ignored and can be used
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
141 for comments. Empty lines are also ignored, too.
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
142
49
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
143 .. note:: if you're performing message extraction using the command Babel
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
144 provides for integration into ``setup.py`` scripts (see below), you
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
145 can also provide this configuration in a different way, namely as a
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
146 keyword argument to the ``setup()`` function.
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
147
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
148
49
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
149 ----------
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
150 Front-Ends
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
151 ----------
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
152
49
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
153 Babel provides two different front-ends to access its functionality for working
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
154 with message catalogs:
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
155
49
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
156 * A `Command-line interface <cmdline.html>`_, and
76
c659c39e0eee Typo on `doc/catalogs.txt`.
palgarvio
parents: 73
diff changeset
157 * `Integration with distutils/setuptools <setup.html>`_
49
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
158
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
159 Which one you choose depends on the nature of your project. For most modern
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
160 Python projects, the distutils/setuptools integration is probably more
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
161 convenient.
37bd476dafe4 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
162
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
163
48
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
164 --------------------------
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
165 Writing Extraction Methods
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
166 --------------------------
22b90b3b161a Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
167
73
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
168 Adding new methods for extracting localizable methods is easy. First, you'll
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
169 need to implement a function that complies with the following interface:
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
170
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
171 .. code-block:: python
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
172
73
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
173 def extract_xxx(fileobj, keywords, options):
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
174 """Extract messages from XXX files.
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
175
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
176 :param fileobj: the file-like object the messages should be extracted
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
177 from
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
178 :param keywords: a list of keywords (i.e. function names) that should
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
179 be recognized as translation functions
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
180 :param options: a dictionary of additional options (optional)
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
181 :return: an iterator over ``(lineno, funcname, message)`` tuples
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
182 :rtype: ``iterator``
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
183 """
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
184
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
185 Next, you should register that function as an entry point. This requires your
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
186 ``setup.py`` script to use `setuptools`_, and your package to be installed with
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
187 the necessary metadata. If that's taken care of, add something like the
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
188 following to your ``setup.py`` script:
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
189
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
190 .. code-block:: python
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
191
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
192 def setup(...
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
193
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
194 entry_points = """
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
195 [babel.extractors]
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
196 xxx = your.package:extract_xxx
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
197 """,
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
198
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
199 That is, add your extraction method to the entry point group
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
200 ``babel.extractors``, where the name of the entry point is the name that people
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
201 will use to reference the extraction method, and the value being the module and
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
202 the name of the function (separated by a colon) implementing the actual
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
203 extraction.
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
204
9bc73c0bf7e5 Extended the docs a bit.
cmlenz
parents: 49
diff changeset
205 .. _`setuptools`: http://peak.telecommunity.com/DevCenter/setuptools
Copyright (C) 2012-2017 Edgewall Software