|
263
|
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 cmdclass = {'compile_catalog': babel.compile_catalog,
|
|
|
23 'extract_messages': babel.extract_messages,
|
|
|
24 'init_catalog': babel.init_catalog,
|
|
|
25 'update_catalog': babel.update_catalog}
|
|
|
26 )
|
|
|
27
|
|
|
28
|
|
|
29 .. contents:: Contents
|
|
|
30 :depth: 2
|
|
|
31 .. sectnum::
|
|
|
32
|
|
|
33
|
|
|
34 compile_catalog
|
|
|
35 ===============
|
|
|
36
|
|
|
37 The ``compile_catalog`` command is similar to the GNU ``msgfmt`` tool, in that
|
|
|
38 it takes a message catalog from a PO file and compiles it to a binary MO file.
|
|
|
39
|
|
|
40 If the command has been correctly installed or registered, a project's
|
|
|
41 ``setup.py`` script should allow you to use the command::
|
|
|
42
|
|
|
43 $ ./setup.py compile_catalog --help
|
|
|
44 Global options:
|
|
|
45 --verbose (-v) run verbosely (default)
|
|
|
46 --quiet (-q) run quietly (turns verbosity off)
|
|
|
47 --dry-run (-n) don't actually do anything
|
|
|
48 --help (-h) show detailed help message
|
|
|
49
|
|
|
50 Options for 'compile_catalog' command:
|
|
|
51 ...
|
|
|
52
|
|
501
|
53 Running the command will produce a binary MO file::
|
|
263
|
54
|
|
|
55 $ ./setup.py compile_catalog --directory foobar/locale --locale pt_BR
|
|
|
56 running compile_catalog
|
|
501
|
57 compiling catalog to foobar/locale/pt_BR/LC_MESSAGES/messages.mo
|
|
263
|
58
|
|
|
59
|
|
|
60 Options
|
|
|
61 -------
|
|
|
62
|
|
|
63 The ``compile_catalog`` command accepts the following options:
|
|
|
64
|
|
323
|
65 +-----------------------------+---------------------------------------------+
|
|
|
66 | Option | Description |
|
|
|
67 +=============================+=============================================+
|
|
|
68 | ``--domain`` | domain of the PO file (defaults to |
|
|
|
69 | | lower-cased project name) |
|
|
|
70 +-----------------------------+---------------------------------------------+
|
|
|
71 | ``--directory`` (``-d``) | name of the base directory |
|
|
|
72 +-----------------------------+---------------------------------------------+
|
|
|
73 | ``--input-file`` (``-i``) | name of the input file |
|
|
|
74 +-----------------------------+---------------------------------------------+
|
|
|
75 | ``--output-file`` (``-o``) | name of the output file |
|
|
|
76 +-----------------------------+---------------------------------------------+
|
|
|
77 | ``--locale`` (``-l``) | locale for the new localized string |
|
|
|
78 +-----------------------------+---------------------------------------------+
|
|
|
79 | ``--use-fuzzy`` (``-f``) | also include "fuzzy" translations |
|
|
|
80 +-----------------------------+---------------------------------------------+
|
|
|
81 | ``--statistics`` | print statistics about translations |
|
|
|
82 +-----------------------------+---------------------------------------------+
|
|
263
|
83
|
|
|
84 If ``directory`` is specified, but ``output-file`` is not, the default filename
|
|
|
85 of the output file will be::
|
|
|
86
|
|
|
87 <directory>/<locale>/LC_MESSAGES/<domain>.mo
|
|
|
88
|
|
|
89 If neither the ``input_file`` nor the ``locale`` option is set, this command
|
|
|
90 looks for all catalog files in the base directory that match the given domain,
|
|
|
91 and compiles each of them to MO files in the same directory.
|
|
|
92
|
|
|
93 These options can either be specified on the command-line, or in the
|
|
|
94 ``setup.cfg`` file.
|
|
|
95
|
|
|
96
|
|
|
97 extract_messages
|
|
|
98 ================
|
|
|
99
|
|
|
100 The ``extract_messages`` command is comparable to the GNU ``xgettext`` program:
|
|
|
101 it can extract localizable messages from a variety of difference source files,
|
|
|
102 and generate a PO (portable object) template file from the collected messages.
|
|
|
103
|
|
|
104 If the command has been correctly installed or registered, a project's
|
|
|
105 ``setup.py`` script should allow you to use the command::
|
|
|
106
|
|
|
107 $ ./setup.py extract_messages --help
|
|
|
108 Global options:
|
|
|
109 --verbose (-v) run verbosely (default)
|
|
|
110 --quiet (-q) run quietly (turns verbosity off)
|
|
|
111 --dry-run (-n) don't actually do anything
|
|
|
112 --help (-h) show detailed help message
|
|
|
113
|
|
|
114 Options for 'extract_messages' command:
|
|
|
115 ...
|
|
|
116
|
|
|
117 Running the command will produce a PO template file::
|
|
|
118
|
|
|
119 $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
|
|
|
120 running extract_messages
|
|
|
121 extracting messages from foobar/__init__.py
|
|
|
122 extracting messages from foobar/core.py
|
|
|
123 ...
|
|
|
124 writing PO template file to foobar/locale/messages.pot
|
|
|
125
|
|
|
126
|
|
|
127 Method Mapping
|
|
|
128 --------------
|
|
|
129
|
|
|
130 The mapping of file patterns to extraction methods (and options) can be
|
|
|
131 specified using a configuration file that is pointed to using the
|
|
|
132 ``--mapping-file`` option shown above. Alternatively, you can configure the
|
|
|
133 mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
|
|
|
134 function:
|
|
|
135
|
|
|
136 .. code-block:: python
|
|
|
137
|
|
|
138 setup(...
|
|
|
139
|
|
|
140 message_extractors = {
|
|
|
141 'foobar': [
|
|
|
142 ('**.py', 'python', None),
|
|
|
143 ('**/templates/**.html', 'genshi', None),
|
|
|
144 ('**/templates/**.txt', 'genshi', {
|
|
|
145 'template_class': 'genshi.template:TextTemplate'
|
|
|
146 })
|
|
|
147 ],
|
|
|
148 },
|
|
|
149
|
|
|
150 ...
|
|
|
151 )
|
|
|
152
|
|
|
153
|
|
|
154 Options
|
|
|
155 -------
|
|
|
156
|
|
|
157 The ``extract_messages`` command accepts the following options:
|
|
|
158
|
|
|
159 +-----------------------------+----------------------------------------------+
|
|
|
160 | Option | Description |
|
|
|
161 +=============================+==============================================+
|
|
|
162 | ``--charset`` | charset to use in the output file |
|
|
|
163 +-----------------------------+----------------------------------------------+
|
|
|
164 | ``--keywords`` (``-k``) | space-separated list of keywords to look for |
|
|
|
165 | | in addition to the defaults |
|
|
|
166 +-----------------------------+----------------------------------------------+
|
|
|
167 | ``--no-default-keywords`` | do not include the default keywords |
|
|
|
168 +-----------------------------+----------------------------------------------+
|
|
|
169 | ``--mapping-file`` (``-F``) | path to the mapping configuration file |
|
|
|
170 +-----------------------------+----------------------------------------------+
|
|
|
171 | ``--no-location`` | do not include location comments with |
|
|
|
172 | | filename and line number |
|
|
|
173 +-----------------------------+----------------------------------------------+
|
|
|
174 | ``--omit-header`` | do not include msgid "" entry in header |
|
|
|
175 +-----------------------------+----------------------------------------------+
|
|
|
176 | ``--output-file`` (``-o``) | name of the output file |
|
|
|
177 +-----------------------------+----------------------------------------------+
|
|
|
178 | ``--width`` (``-w``) | set output line width (default 76) |
|
|
|
179 +-----------------------------+----------------------------------------------+
|
|
|
180 | ``--no-wrap`` | do not break long message lines, longer than |
|
|
|
181 | | the output line width, into several lines |
|
|
|
182 +-----------------------------+----------------------------------------------+
|
|
|
183 | ``--input-dirs`` | directories that should be scanned for |
|
|
|
184 | | messages |
|
|
|
185 +-----------------------------+----------------------------------------------+
|
|
|
186 | ``--sort-output`` | generate sorted output (default False) |
|
|
|
187 +-----------------------------+----------------------------------------------+
|
|
|
188 | ``--sort-by-file`` | sort output by file location (default False) |
|
|
|
189 +-----------------------------+----------------------------------------------+
|
|
|
190 | ``--msgid-bugs-address`` | set email address for message bug reports |
|
|
|
191 +-----------------------------+----------------------------------------------+
|
|
|
192 | ``--copyright-holder`` | set copyright holder in output |
|
|
|
193 +-----------------------------+----------------------------------------------+
|
|
|
194 | ``--add-comments (-c)`` | place comment block with TAG (or those |
|
|
|
195 | | preceding keyword lines) in output file. |
|
|
|
196 | | Separate multiple TAGs with commas(,) |
|
|
|
197 +-----------------------------+----------------------------------------------+
|
|
|
198
|
|
|
199 These options can either be specified on the command-line, or in the
|
|
|
200 ``setup.cfg`` file. In the latter case, the options above become entries of the
|
|
|
201 section ``[extract_messages]``, and the option names are changed to use
|
|
|
202 underscore characters instead of dashes, for example:
|
|
|
203
|
|
|
204 .. code-block:: ini
|
|
|
205
|
|
|
206 [extract_messages]
|
|
557
|
207 keywords = _ gettext ngettext
|
|
263
|
208 mapping_file = babel.cfg
|
|
|
209 width = 80
|
|
|
210
|
|
|
211 This would be equivalent to invoking the command from the command-line as
|
|
|
212 follows::
|
|
|
213
|
|
|
214 $ setup.py extract_messages -k _ -k gettext -k ngettext -F mapping.cfg -w 80
|
|
|
215
|
|
|
216 Any path names are interpreted relative to the location of the ``setup.py``
|
|
|
217 file. For boolean options, use "true" or "false" values.
|
|
|
218
|
|
|
219
|
|
|
220 init_catalog
|
|
|
221 ============
|
|
|
222
|
|
|
223 The ``init_catalog`` command is basically equivalent to the GNU ``msginit``
|
|
|
224 program: it creates a new translation catalog based on a PO template file (POT).
|
|
|
225
|
|
|
226 If the command has been correctly installed or registered, a project's
|
|
|
227 ``setup.py`` script should allow you to use the command::
|
|
|
228
|
|
|
229 $ ./setup.py init_catalog --help
|
|
|
230 Global options:
|
|
|
231 --verbose (-v) run verbosely (default)
|
|
|
232 --quiet (-q) run quietly (turns verbosity off)
|
|
|
233 --dry-run (-n) don't actually do anything
|
|
|
234 --help (-h) show detailed help message
|
|
|
235
|
|
|
236 Options for 'init_catalog' command:
|
|
|
237 ...
|
|
|
238
|
|
|
239 Running the command will produce a PO file::
|
|
|
240
|
|
|
241 $ ./setup.py init_catalog -l fr -i foobar/locales/messages.pot \
|
|
|
242 -o foobar/locales/fr/messages.po
|
|
|
243 running init_catalog
|
|
|
244 creating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
|
|
|
245
|
|
|
246
|
|
|
247 Options
|
|
|
248 -------
|
|
|
249
|
|
|
250 The ``init_catalog`` command accepts the following options:
|
|
|
251
|
|
323
|
252 +-----------------------------+---------------------------------------------+
|
|
|
253 | Option | Description |
|
|
|
254 +=============================+=============================================+
|
|
|
255 | ``--domain`` | domain of the PO file (defaults to |
|
|
|
256 | | lower-cased project name) |
|
|
|
257 +-----------------------------+---------------------------------------------+
|
|
|
258 | ``--input-file`` (``-i``) | name of the input file |
|
|
|
259 +-----------------------------+---------------------------------------------+
|
|
|
260 | ``--output-dir`` (``-d``) | name of the output directory |
|
|
|
261 +-----------------------------+---------------------------------------------+
|
|
|
262 | ``--output-file`` (``-o``) | name of the output file |
|
|
|
263 +-----------------------------+---------------------------------------------+
|
|
|
264 | ``--locale`` | locale for the new localized string |
|
|
|
265 +-----------------------------+---------------------------------------------+
|
|
263
|
266
|
|
|
267 If ``output-dir`` is specified, but ``output-file`` is not, the default filename
|
|
|
268 of the output file will be::
|
|
|
269
|
|
|
270 <output_dir>/<locale>/LC_MESSAGES/<domain>.po
|
|
|
271
|
|
|
272 These options can either be specified on the command-line, or in the
|
|
|
273 ``setup.cfg`` file.
|
|
|
274
|
|
|
275
|
|
|
276 update_catalog
|
|
|
277 ==============
|
|
|
278
|
|
|
279 The ``update_catalog`` command is basically equivalent to the GNU ``msgmerge``
|
|
|
280 program: it updates an existing translations catalog based on a PO template
|
|
|
281 file (POT).
|
|
|
282
|
|
|
283 If the command has been correctly installed or registered, a project's
|
|
|
284 ``setup.py`` script should allow you to use the command::
|
|
|
285
|
|
|
286 $ ./setup.py update_catalog --help
|
|
|
287 Global options:
|
|
|
288 --verbose (-v) run verbosely (default)
|
|
|
289 --quiet (-q) run quietly (turns verbosity off)
|
|
|
290 --dry-run (-n) don't actually do anything
|
|
|
291 --help (-h) show detailed help message
|
|
|
292
|
|
|
293 Options for 'update_catalog' command:
|
|
|
294 ...
|
|
|
295
|
|
|
296 Running the command will update a PO file::
|
|
|
297
|
|
|
298 $ ./setup.py update_catalog -l fr -i foobar/locales/messages.pot \
|
|
|
299 -o foobar/locales/fr/messages.po
|
|
|
300 running update_catalog
|
|
|
301 updating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
|
|
|
302
|
|
|
303
|
|
|
304 Options
|
|
|
305 -------
|
|
|
306
|
|
|
307 The ``update_catalog`` command accepts the following options:
|
|
|
308
|
|
323
|
309 +-------------------------------------+-------------------------------------+
|
|
|
310 | Option | Description |
|
|
|
311 +=====================================+=====================================+
|
|
|
312 | ``--domain`` | domain of the PO file (defaults to |
|
|
|
313 | | lower-cased project name) |
|
|
|
314 +-------------------------------------+-------------------------------------+
|
|
|
315 | ``--input-file`` (``-i``) | name of the input file |
|
|
|
316 +-------------------------------------+-------------------------------------+
|
|
|
317 | ``--output-dir`` (``-d``) | name of the output directory |
|
|
|
318 +-------------------------------------+-------------------------------------+
|
|
|
319 | ``--output-file`` (``-o``) | name of the output file |
|
|
|
320 +-------------------------------------+-------------------------------------+
|
|
|
321 | ``--locale`` | locale for the new localized string |
|
|
|
322 +-------------------------------------+-------------------------------------+
|
|
|
323 | ``--ignore-obsolete`` | do not include obsolete messages in |
|
|
|
324 | | the output |
|
|
|
325 +-------------------------------------+-------------------------------------+
|
|
|
326 | ``--no-fuzzy-matching`` (``-N``) | do not use fuzzy matching |
|
|
|
327 +-------------------------------------+-------------------------------------+
|
|
|
328 | ``--previous`` | keep previous msgids of translated |
|
|
|
329 | | messages |
|
|
|
330 +-------------------------------------+-------------------------------------+
|
|
263
|
331
|
|
|
332 If ``output-dir`` is specified, but ``output-file`` is not, the default filename
|
|
|
333 of the output file will be::
|
|
|
334
|
|
|
335 <output_dir>/<locale>/LC_MESSAGES/<domain>.po
|
|
|
336
|
|
|
337 If neither the ``input_file`` nor the ``locale`` option is set, this command
|
|
|
338 looks for all catalog files in the base directory that match the given domain,
|
|
|
339 and updates each of them.
|
|
|
340
|
|
|
341 These options can either be specified on the command-line, or in the
|
|
|
342 ``setup.cfg`` file.
|
