|
142
|
1 .. -*- mode: rst; encoding: utf-8 -*-
|
|
|
2
|
|
|
3 ================================
|
|
|
4 Distutils/Setuptools Integration
|
|
|
5 ================================
|
|
|
6
|
|
|
7 Babel provides commands for integration into ``setup.py`` scripts, based on
|
|
|
8 either the ``distutils`` package that is part of the Python standard library,
|
|
|
9 or the third-party ``setuptools`` package.
|
|
|
10
|
|
|
11 These commands are available by default when Babel has been properly installed,
|
|
|
12 and ``setup.py`` is using ``setuptools``. For projects that use plain old
|
|
|
13 ``distutils``, the commands need to be registered explicitly, for example:
|
|
|
14
|
|
|
15 .. code-block:: python
|
|
|
16
|
|
|
17 from distutils.core import setup
|
|
|
18 from babel.messages import frontend as babel
|
|
|
19
|
|
|
20 setup(
|
|
|
21 ...
|
|
|
22 cmd_class = {'extract_messages': babel.extract_messages,
|
|
|
23 'new_catalog': babel.new_catalog}
|
|
|
24 )
|
|
|
25
|
|
|
26
|
|
|
27 .. contents:: Contents
|
|
|
28 :depth: 2
|
|
|
29 .. sectnum::
|
|
|
30
|
|
|
31
|
|
|
32 extract_messages
|
|
|
33 ================
|
|
|
34
|
|
|
35 The ``extract_messages`` command is comparable to the GNU ``xgettext`` program:
|
|
|
36 it can extract localizable messages from a variety of difference source files,
|
|
|
37 and generate a PO (portable object) template file from the collected messages.
|
|
|
38
|
|
|
39 If the command has been correctly installed or registered, another project's
|
|
|
40 ``setup.py`` script should allow you to use the command::
|
|
|
41
|
|
|
42 $ ./setup.py extract_messages --help
|
|
|
43 Global options:
|
|
|
44 --verbose (-v) run verbosely (default)
|
|
|
45 --quiet (-q) run quietly (turns verbosity off)
|
|
|
46 --dry-run (-n) don't actually do anything
|
|
|
47 --help (-h) show detailed help message
|
|
|
48
|
|
|
49 Options for 'extract_messages' command:
|
|
|
50 ...
|
|
|
51
|
|
|
52 Running the command will produce a PO template file::
|
|
|
53
|
|
|
54 $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
|
|
|
55 running extract_messages
|
|
|
56 extracting messages from foobar/__init__.py
|
|
|
57 extracting messages from foobar/core.py
|
|
|
58 ...
|
|
|
59 writing PO template file to foobar/locale/messages.pot
|
|
|
60
|
|
|
61
|
|
|
62 Method Mapping
|
|
|
63 --------------
|
|
|
64
|
|
|
65 The mapping of file patterns to extraction methods (and options) can be
|
|
|
66 specified using a configuration file that is pointed to using the
|
|
|
67 ``--mapping-file`` option shown above. Alternatively, you can configure the
|
|
|
68 mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
|
|
|
69 function:
|
|
|
70
|
|
|
71 .. code-block:: python
|
|
|
72
|
|
|
73 setup(...
|
|
|
74
|
|
|
75 message_extractors = {
|
|
|
76 'foobar': [
|
|
|
77 ('**.py', 'python', None),
|
|
|
78 ('**/templates/**.html', 'genshi', None),
|
|
|
79 ('**/templates/**.txt', 'genshi', {
|
|
|
80 'template_class': 'genshi.template.text.TextTemplate'
|
|
|
81 })
|
|
|
82 ],
|
|
|
83 },
|
|
|
84
|
|
|
85 ...
|
|
|
86 )
|
|
|
87
|
|
|
88
|
|
|
89 Options
|
|
|
90 -------
|
|
|
91
|
|
|
92 The ``extract_messages`` command accepts the following options:
|
|
|
93
|
|
|
94 +-----------------------------+----------------------------------------------+
|
|
|
95 | Option | Description |
|
|
|
96 +=============================+==============================================+
|
|
|
97 | ``--charset`` | charset to use in the output file |
|
|
|
98 +-----------------------------+----------------------------------------------+
|
|
|
99 | ``--keywords`` (``-k``) | space-separated list of keywords to look for |
|
|
|
100 | | in addition to the defaults |
|
|
|
101 +-----------------------------+----------------------------------------------+
|
|
|
102 | ``--no-default-keywords`` | do not include the default keywords |
|
|
|
103 +-----------------------------+----------------------------------------------+
|
|
|
104 | ``--mapping-file`` (``-F``) | path to the mapping configuration file |
|
|
|
105 +-----------------------------+----------------------------------------------+
|
|
|
106 | ``--no-location`` | do not include location comments with |
|
|
|
107 | | filename and line number |
|
|
|
108 +-----------------------------+----------------------------------------------+
|
|
|
109 | ``--omit-header`` | do not include msgid "" entry in header |
|
|
|
110 +-----------------------------+----------------------------------------------+
|
|
|
111 | ``--output-file`` (``-o``) | name of the output file |
|
|
|
112 +-----------------------------+----------------------------------------------+
|
|
|
113 | ``--width`` (``-w``) | set output line width (default 76) |
|
|
|
114 +-----------------------------+----------------------------------------------+
|
|
|
115 | ``--no-wrap`` | do not break long message lines, longer than |
|
|
|
116 | | the output line width, into several lines |
|
|
|
117 +-----------------------------+----------------------------------------------+
|
|
|
118 | ``--input-dirs`` | directories that should be scanned for |
|
|
|
119 | | messages |
|
|
|
120 +-----------------------------+----------------------------------------------+
|
|
|
121 | ``--sort-output`` | generate sorted output (default False) |
|
|
|
122 +-----------------------------+----------------------------------------------+
|
|
|
123 | ``--sort-by-file`` | sort output by file location (default False) |
|
|
|
124 +-----------------------------+----------------------------------------------+
|
|
|
125 | ``--msgid-bugs-address`` | set email address for message bug reports |
|
|
|
126 +-----------------------------+----------------------------------------------+
|
|
|
127 | ``--copyright-holder`` | set copyright holder in output |
|
|
|
128 +-----------------------------+----------------------------------------------+
|
|
|
129 | ``--add-comments (-c)`` | place comment block with TAG (or those |
|
|
|
130 | | preceding keyword lines) in output file. |
|
|
|
131 | | Separate multiple TAGs with commas(,) |
|
|
|
132 +-----------------------------+----------------------------------------------+
|
|
|
133
|
|
|
134 These options can either be specified on the command-line, or in the
|
|
|
135 ``setup.cfg`` file. In the latter case, the options above become entries of the
|
|
|
136 section ``[extract_messages]``, and the option names are changed to use
|
|
|
137 underscore characters instead of dashes, for example:
|
|
|
138
|
|
|
139 .. code-block:: ini
|
|
|
140
|
|
|
141 [extract_messages]
|
|
|
142 keywords = _, gettext, ngettext
|
|
|
143 mapping_file = babel.cfg
|
|
|
144 width = 80
|
|
|
145
|
|
|
146 This would be equivalent to invoking the command from the command-line as
|
|
|
147 follows::
|
|
|
148
|
|
|
149 $ setup.py extract_messages -k _ -k gettext -k ngettext -F mapping.cfg -w 80
|
|
|
150
|
|
|
151 Any path names are interpreted relative to the location of the ``setup.py``
|
|
|
152 file. For boolean options, use "true" or "false" values.
|
|
|
153
|
|
|
154
|
|
|
155 new_catalog
|
|
|
156 ===========
|
|
|
157
|
|
|
158 The ``new_catalog`` command is basically equivalent to the GNU ``msginit``
|
|
|
159 program: it creates a new translation catalog based on a PO template file (POT).
|
|
|
160
|
|
|
161 If the command has been correctly installed or registered, another project's
|
|
|
162 ``setup.py`` script should allow you to use the command::
|
|
|
163
|
|
|
164 $ ./setup.py new_catalog --help
|
|
|
165 Global options:
|
|
|
166 --verbose (-v) run verbosely (default)
|
|
|
167 --quiet (-q) run quietly (turns verbosity off)
|
|
|
168 --dry-run (-n) don't actually do anything
|
|
|
169 --help (-h) show detailed help message
|
|
|
170
|
|
|
171 Options for 'new_catalog' command:
|
|
|
172 ...
|
|
|
173
|
|
|
174 Running the command will produce a PO file::
|
|
|
175
|
|
|
176 $ ./setup.py new_catalog -l fr -i foobar/locales/messages.pot \
|
|
|
177 -o foobar/locales/fr/messages.po
|
|
|
178 running new_catalog
|
|
|
179 creating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
|
|
|
180
|
|
|
181
|
|
|
182 Options
|
|
|
183 -------
|
|
|
184
|
|
|
185 The ``new_catalog`` command accepts the following options:
|
|
|
186
|
|
|
187 +-----------------------------+----------------------------------------------+
|
|
|
188 | Option | Description |
|
|
|
189 +=============================+==============================================+
|
|
|
190 | ``--domain`` | domain of the PO file (defaults to |
|
|
|
191 | | lower-cased project name) |
|
|
|
192 +-----------------------------+----------------------------------------------+
|
|
|
193 | ``--input-file`` (``-i``) | name of the input file |
|
|
|
194 +-----------------------------+----------------------------------------------+
|
|
|
195 | ``--output-dir`` (``-d``) | name of the output directory |
|
|
|
196 +-----------------------------+----------------------------------------------+
|
|
|
197 | ``--output-file`` (``-o``) | name of the output file |
|
|
|
198 +-----------------------------+----------------------------------------------+
|
|
|
199 | ``--locale`` | locale for the new localized string |
|
|
|
200 +-----------------------------+----------------------------------------------+
|
|
|
201 | ``--omit-header`` | do not include msgid "" entry in header |
|
|
|
202 +-----------------------------+----------------------------------------------+
|
|
|
203 | ``--first-author`` | name of the first author |
|
|
|
204 +-----------------------------+----------------------------------------------+
|
|
|
205 | ``--first-author-email`` | email address of the first author |
|
|
|
206 +-----------------------------+----------------------------------------------+
|
|
|
207
|
|
|
208 If ``output-dir`` is specified, but ``output-file`` is not, the default filename
|
|
|
209 of the output file will be::
|
|
|
210
|
|
|
211 <output_dir>/<locale>/LC_MESSAGES/<domain>.po
|
|
|
212
|
|
|
213 These options can either be specified on the command-line, or in the
|
|
|
214 ``setup.cfg`` file.
|
