Mercurial > babel > old > babel-test

annotate doc/catalogs.txt @ 78:ee043bb666f0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed the plurals header on `Catalog` which should only be written if it's not a catalog template. Added support to the frontends for `--msgid-bugs-address` that set's the `Report-Msgid-Bugs-To` header, which was also a missing header on `Catalog`, so, a bug found by chance :) (See #12, item 6)
author palgarvio
date Sun, 10 Jun 2007 08:42:21 +0000
parents 3ed77bf655d1
children 1e89661e6b26
rev   line source
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
3 =============================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
4 Working with Message Catalogs
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
5 =============================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7 .. contents:: Contents
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 :depth: 2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 .. sectnum::
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12 Introduction
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
13 ============
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
14
b2492365f186 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
16 application as subject to localization, by wrapping them in functions such as
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
17 ``gettext(str)`` and ``ngettext(singular, plural, num)``. For brevity, the
40
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
18 ``gettext`` function is often aliased to ``_(str)``, so you can write:
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
19
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
20 .. code-block:: python
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
21
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
22 print _("Hello")
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
23
40
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
24 instead of just:
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
25
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
26 .. code-block:: python
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
27
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
28 print "Hello"
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
29
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
30 to make the string "Hello" localizable.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
31
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
32 Message catalogs are collections of translations for such localizable messages
b2492365f186 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
b2492365f186 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`_
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
35 tools and the GNU `translation project`_.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
36
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
37 .. _`gettext`: http://www.gnu.org/software/gettext/
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
38 .. _`translation project`: http://sourceforge.net/projects/translation
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
39
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
40 The general procedure for building message catalogs looks something like this:
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
41
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
42 * use a tool (such as ``xgettext``) to extract localizable strings from the
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
43 code base and write them to a POT (PO Template) file.
b2492365f186 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")
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
45 and start translating the messages
b2492365f186 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
47 MO file
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
48 * later, when code changes make it necessary to update the translations, you
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
49 regenerate the POT file and merge the changes into the various
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
50 locale-specific PO files, for example using ``msgmerge``
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
51
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
52 Python provides the `gettext module`_ as part of the standard library, which
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
53 enables applications to work with appropriately generated MO files.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
54
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
55 .. _`gettext module`: http://docs.python.org/lib/module-gettext.html
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
56
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
57 As ``gettext`` provides a solid and well supported foundation for translating
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
58 application messages, Babel does not reinvent the wheel, but rather reuses this
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
59 infrastructure, and makes it easier to build message catalogs for Python
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
60 applications.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
61
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
62
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
63 Message Extraction
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
64 ==================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
65
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
66 Babel provides functionality similar to that of the ``xgettext`` program,
b2492365f186 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
68 for other file formats can be added using a simple extension mechanism.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
69
48
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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``,
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
76
bd647e3760e0 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,
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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,
bd647e3760e0 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`_
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
86
bd647e3760e0 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/
bd647e3760e0 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/
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
89
bd647e3760e0 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
bd647e3760e0 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
92
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
93
48
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
94 .. _`mapping`:
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
95
48
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
96 -------------------------------------------
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
98 -------------------------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
99
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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).
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
104
bd647e3760e0 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
bd647e3760e0 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:
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
107
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
108 .. code-block:: ini
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
109
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
111
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
112 [python: foobar/**.py]
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
113
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
115
bd647e3760e0 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]
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
119
bd647e3760e0 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]
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
123
bd647e3760e0 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``
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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,
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
131
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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 "/"),
bd647e3760e0 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,
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
139
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
142
49
daf35e2ad044 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
daf35e2ad044 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
daf35e2ad044 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
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
146 keyword argument to the ``setup()`` function.
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
147
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
148
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
149 ----------
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
150 Front-Ends
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
151 ----------
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
152
49
daf35e2ad044 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
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
154 with message catalogs:
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
155
49
daf35e2ad044 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
3ed77bf655d1 Typo on `doc/catalogs.txt`.
palgarvio
parents: 73
diff changeset
157 * `Integration with distutils/setuptools <setup.html>`_
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
158
daf35e2ad044 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
daf35e2ad044 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
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
161 convenient.
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
162
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
163
48
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
164 --------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
165 Writing Extraction Methods
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
166 --------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
167
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
168 Adding new methods for extracting localizable methods is easy. First, you'll
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
169 need to implement a function that complies with the following interface:
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
170
40
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
171 .. code-block:: python
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
172
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
173 def extract_xxx(fileobj, keywords, options):
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
174 """Extract messages from XXX files.
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
175
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
176 :param fileobj: the file-like object the messages should be extracted
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
177 from
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
178 :param keywords: a list of keywords (i.e. function names) that should
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
179 be recognized as translation functions
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
180 :param options: a dictionary of additional options (optional)
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
181 :return: an iterator over ``(lineno, funcname, message)`` tuples
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
182 :rtype: ``iterator``
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
183 """
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
184
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
185 Next, you should register that function as an entry point. This requires your
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
186 ``setup.py`` script to use `setuptools`_, and your package to be installed with
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
187 the necessary metadata. If that's taken care of, add something like the
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
188 following to your ``setup.py`` script:
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
189
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
190 .. code-block:: python
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
191
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
192 def setup(...
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
193
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
194 entry_points = """
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
195 [babel.extractors]
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
196 xxx = your.package:extract_xxx
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
197 """,
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
198
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
199 That is, add your extraction method to the entry point group
dd5c3ba59eae 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
dd5c3ba59eae 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
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
202 the name of the function (separated by a colon) implementing the actual
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
203 extraction.
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
204
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
205 .. _`setuptools`: http://peak.telecommunity.com/DevCenter/setuptools
Copyright (C) 2012-2017 Edgewall Software