1
.. -*- mode: rst; encoding: utf-8 -*-
5
================================
6
Distutils/Setuptools Integration
7
================================
9
Babel provides commands for integration into ``setup.py`` scripts, based on
10
either the ``distutils`` package that is part of the Python standard library,
11
or the third-party ``setuptools`` package.
13
These commands are available by default when Babel has been properly installed,
14
and ``setup.py`` is using ``setuptools``. For projects that use plain old
15
``distutils``, the commands need to be registered explicitly, for example:
17
.. code-block:: python
19
from distutils.core import setup
20
from babel.messages import frontend as babel
24
cmdclass = {'compile_catalog': babel.compile_catalog,
25
'extract_messages': babel.extract_messages,
26
'init_catalog': babel.init_catalog,
27
'update_catalog': babel.update_catalog}
34
The ``compile_catalog`` command is similar to the GNU ``msgfmt`` tool, in that
35
it takes a message catalog from a PO file and compiles it to a binary MO file.
37
If the command has been correctly installed or registered, a project's
38
``setup.py`` script should allow you to use the command::
40
$ ./setup.py compile_catalog --help
42
--verbose (-v) run verbosely (default)
43
--quiet (-q) run quietly (turns verbosity off)
44
--dry-run (-n) don't actually do anything
45
--help (-h) show detailed help message
47
Options for 'compile_catalog' command:
50
Running the command will produce a binary MO file::
52
$ ./setup.py compile_catalog --directory foobar/locale --locale pt_BR
53
running compile_catalog
54
compiling catalog to foobar/locale/pt_BR/LC_MESSAGES/messages.mo
60
The ``compile_catalog`` command accepts the following options:
62
+-----------------------------+---------------------------------------------+
63
| Option | Description |
64
+=============================+=============================================+
65
| ``--domain`` | domain of the PO file (defaults to |
66
| | lower-cased project name) |
67
+-----------------------------+---------------------------------------------+
68
| ``--directory`` (``-d``) | name of the base directory |
69
+-----------------------------+---------------------------------------------+
70
| ``--input-file`` (``-i``) | name of the input file |
71
+-----------------------------+---------------------------------------------+
72
| ``--output-file`` (``-o``) | name of the output file |
73
+-----------------------------+---------------------------------------------+
74
| ``--locale`` (``-l``) | locale for the new localized string |
75
+-----------------------------+---------------------------------------------+
76
| ``--use-fuzzy`` (``-f``) | also include "fuzzy" translations |
77
+-----------------------------+---------------------------------------------+
78
| ``--statistics`` | print statistics about translations |
79
+-----------------------------+---------------------------------------------+
81
If ``directory`` is specified, but ``output-file`` is not, the default filename
82
of the output file will be::
84
<directory>/<locale>/LC_MESSAGES/<domain>.mo
86
If neither the ``input_file`` nor the ``locale`` option is set, this command
87
looks for all catalog files in the base directory that match the given domain,
88
and compiles each of them to MO files in the same directory.
90
These options can either be specified on the command-line, or in the
97
The ``extract_messages`` command is comparable to the GNU ``xgettext`` program:
98
it can extract localizable messages from a variety of difference source files,
99
and generate a PO (portable object) template file from the collected messages.
101
If the command has been correctly installed or registered, a project's
102
``setup.py`` script should allow you to use the command::
104
$ ./setup.py extract_messages --help
106
--verbose (-v) run verbosely (default)
107
--quiet (-q) run quietly (turns verbosity off)
108
--dry-run (-n) don't actually do anything
109
--help (-h) show detailed help message
111
Options for 'extract_messages' command:
114
Running the command will produce a PO template file::
116
$ ./setup.py extract_messages --output-file foobar/locale/messages.pot
117
running extract_messages
118
extracting messages from foobar/__init__.py
119
extracting messages from foobar/core.py
121
writing PO template file to foobar/locale/messages.pot
127
The mapping of file patterns to extraction methods (and options) can be
128
specified using a configuration file that is pointed to using the
129
``--mapping-file`` option shown above. Alternatively, you can configure the
130
mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
133
.. code-block:: python
137
message_extractors = {
139
('**.py', 'python', None),
140
('**/templates/**.html', 'genshi', None),
141
('**/templates/**.txt', 'genshi', {
142
'template_class': 'genshi.template:TextTemplate'
154
The ``extract_messages`` command accepts the following options:
156
+-----------------------------+----------------------------------------------+
157
| Option | Description |
158
+=============================+==============================================+
159
| ``--charset`` | charset to use in the output file |
160
+-----------------------------+----------------------------------------------+
161
| ``--keywords`` (``-k``) | space-separated list of keywords to look for |
162
| | in addition to the defaults |
163
+-----------------------------+----------------------------------------------+
164
| ``--no-default-keywords`` | do not include the default keywords |
165
+-----------------------------+----------------------------------------------+
166
| ``--mapping-file`` (``-F``) | path to the mapping configuration file |
167
+-----------------------------+----------------------------------------------+
168
| ``--no-location`` | do not include location comments with |
169
| | filename and line number |
170
+-----------------------------+----------------------------------------------+
171
| ``--omit-header`` | do not include msgid "" entry in header |
172
+-----------------------------+----------------------------------------------+
173
| ``--output-file`` (``-o``) | name of the output file |
174
+-----------------------------+----------------------------------------------+
175
| ``--width`` (``-w``) | set output line width (default 76) |
176
+-----------------------------+----------------------------------------------+
177
| ``--no-wrap`` | do not break long message lines, longer than |
178
| | the output line width, into several lines |
179
+-----------------------------+----------------------------------------------+
180
| ``--input-dirs`` | directories that should be scanned for |
182
+-----------------------------+----------------------------------------------+
183
| ``--sort-output`` | generate sorted output (default False) |
184
+-----------------------------+----------------------------------------------+
185
| ``--sort-by-file`` | sort output by file location (default False) |
186
+-----------------------------+----------------------------------------------+
187
| ``--msgid-bugs-address`` | set email address for message bug reports |
188
+-----------------------------+----------------------------------------------+
189
| ``--copyright-holder`` | set copyright holder in output |
190
+-----------------------------+----------------------------------------------+
191
| ``--add-comments (-c)`` | place comment block with TAG (or those |
192
| | preceding keyword lines) in output file. |
193
| | Separate multiple TAGs with commas(,) |
194
+-----------------------------+----------------------------------------------+
196
These options can either be specified on the command-line, or in the
197
``setup.cfg`` file. In the latter case, the options above become entries of the
198
section ``[extract_messages]``, and the option names are changed to use
199
underscore characters instead of dashes, for example:
204
keywords = _ gettext ngettext
205
mapping_file = babel.cfg
208
This would be equivalent to invoking the command from the command-line as
211
$ setup.py extract_messages -k _ -k gettext -k ngettext -F mapping.cfg -w 80
213
Any path names are interpreted relative to the location of the ``setup.py``
214
file. For boolean options, use "true" or "false" values.
220
The ``init_catalog`` command is basically equivalent to the GNU ``msginit``
221
program: it creates a new translation catalog based on a PO template file (POT).
223
If the command has been correctly installed or registered, a project's
224
``setup.py`` script should allow you to use the command::
226
$ ./setup.py init_catalog --help
228
--verbose (-v) run verbosely (default)
229
--quiet (-q) run quietly (turns verbosity off)
230
--dry-run (-n) don't actually do anything
231
--help (-h) show detailed help message
233
Options for 'init_catalog' command:
236
Running the command will produce a PO file::
238
$ ./setup.py init_catalog -l fr -i foobar/locales/messages.pot \
239
-o foobar/locales/fr/messages.po
241
creating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
247
The ``init_catalog`` command accepts the following options:
249
+-----------------------------+---------------------------------------------+
250
| Option | Description |
251
+=============================+=============================================+
252
| ``--domain`` | domain of the PO file (defaults to |
253
| | lower-cased project name) |
254
+-----------------------------+---------------------------------------------+
255
| ``--input-file`` (``-i``) | name of the input file |
256
+-----------------------------+---------------------------------------------+
257
| ``--output-dir`` (``-d``) | name of the output directory |
258
+-----------------------------+---------------------------------------------+
259
| ``--output-file`` (``-o``) | name of the output file |
260
+-----------------------------+---------------------------------------------+
261
| ``--locale`` | locale for the new localized string |
262
+-----------------------------+---------------------------------------------+
264
If ``output-dir`` is specified, but ``output-file`` is not, the default filename
265
of the output file will be::
267
<output_dir>/<locale>/LC_MESSAGES/<domain>.po
269
These options can either be specified on the command-line, or in the
276
The ``update_catalog`` command is basically equivalent to the GNU ``msgmerge``
277
program: it updates an existing translations catalog based on a PO template
280
If the command has been correctly installed or registered, a project's
281
``setup.py`` script should allow you to use the command::
283
$ ./setup.py update_catalog --help
285
--verbose (-v) run verbosely (default)
286
--quiet (-q) run quietly (turns verbosity off)
287
--dry-run (-n) don't actually do anything
288
--help (-h) show detailed help message
290
Options for 'update_catalog' command:
293
Running the command will update a PO file::
295
$ ./setup.py update_catalog -l fr -i foobar/locales/messages.pot \
296
-o foobar/locales/fr/messages.po
297
running update_catalog
298
updating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
304
The ``update_catalog`` command accepts the following options:
306
+-------------------------------------+-------------------------------------+
307
| Option | Description |
308
+=====================================+=====================================+
309
| ``--domain`` | domain of the PO file (defaults to |
310
| | lower-cased project name) |
311
+-------------------------------------+-------------------------------------+
312
| ``--input-file`` (``-i``) | name of the input file |
313
+-------------------------------------+-------------------------------------+
314
| ``--output-dir`` (``-d``) | name of the output directory |
315
+-------------------------------------+-------------------------------------+
316
| ``--output-file`` (``-o``) | name of the output file |
317
+-------------------------------------+-------------------------------------+
318
| ``--locale`` | locale for the new localized string |
319
+-------------------------------------+-------------------------------------+
320
| ``--ignore-obsolete`` | do not include obsolete messages in |
322
+-------------------------------------+-------------------------------------+
323
| ``--no-fuzzy-matching`` (``-N``) | do not use fuzzy matching |
324
+-------------------------------------+-------------------------------------+
325
| ``--previous`` | keep previous msgids of translated |
327
+-------------------------------------+-------------------------------------+
329
If ``output-dir`` is specified, but ``output-file`` is not, the default filename
330
of the output file will be::
332
<output_dir>/<locale>/LC_MESSAGES/<domain>.po
334
If neither the ``input_file`` nor the ``locale`` option is set, this command
335
looks for all catalog files in the base directory that match the given domain,
336
and updates each of them.
338
These options can either be specified on the command-line, or in the
added
removed
docs/setup.rst
