1.. -*- mode: rst; encoding: utf-8 -*-
2
3.. _setup-integration:
4
5================================
6Distutils/Setuptools Integration
7================================
8
9Babel provides commands for integration into ``setup.py`` scripts, based on
10either the ``distutils`` package that is part of the Python standard library,
11or the third-party ``setuptools`` package.
12
13These commands are available by default when Babel has been properly installed,
14and ``setup.py`` is using ``setuptools``. For projects that use plain old
15``distutils``, the commands need to be registered explicitly, for example:
16
17.. code-block:: python
18
19    from distutils.core import setup
20    from babel.messages import frontend as babel
21
22    setup(
23        ...
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}
28    )
29
30
31compile_catalog
32===============
33
34The ``compile_catalog`` command is similar to the GNU ``msgfmt`` tool, in that
35it takes a message catalog from a PO file and compiles it to a binary MO file.
36
37If the command has been correctly installed or registered, a project's
38``setup.py`` script should allow you to use the command::
39
40    $ ./setup.py compile_catalog --help
41    Global options:
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
46
47    Options for 'compile_catalog' command:
48       ...
49
50Running the command will produce a binary MO file::
51
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
55
56
57Options
58-------
59
60The ``compile_catalog`` command accepts the following options:
61
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  +-----------------------------+---------------------------------------------+
80
81If ``directory`` is specified, but ``output-file`` is not, the default filename
82of the output file will be::
83
84    <directory>/<locale>/LC_MESSAGES/<domain>.mo
85
86If neither the ``input_file`` nor the ``locale`` option is set, this command
87looks for all catalog files in the base directory that match the given domain,
88and compiles each of them to MO files in the same directory.
89
90These options can either be specified on the command-line, or in the
91``setup.cfg`` file.
92
93
94extract_messages
95================
96
97The ``extract_messages`` command is comparable to the GNU ``xgettext`` program:
98it can extract localizable messages from a variety of difference source files,
99and generate a PO (portable object) template file from the collected messages.
100
101If the command has been correctly installed or registered, a project's
102``setup.py`` script should allow you to use the command::
103
104    $ ./setup.py extract_messages --help
105    Global options:
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
110
111    Options for 'extract_messages' command:
112       ...
113
114Running the command will produce a PO template file::
115
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
120    ...
121    writing PO template file to foobar/locale/messages.pot
122
123
124Method Mapping
125--------------
126
127The mapping of file patterns to extraction methods (and options) can be
128specified using a configuration file that is pointed to using the
129``--mapping-file`` option shown above. Alternatively, you can configure the
130mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
131function:
132
133.. code-block:: python
134
135    setup(...
136
137        message_extractors = {
138            'foobar': [
139                ('**.py',                'python', None),
140                ('**/templates/**.html', 'genshi', None),
141                ('**/templates/**.txt',  'genshi', {
142                    'template_class': 'genshi.template:TextTemplate'
143                })
144            ],
145        },
146
147        ...
148    )
149
150
151Options
152-------
153
154The ``extract_messages`` command accepts the following options:
155
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       |
181  |                             | messages                                     |
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  +-----------------------------+----------------------------------------------+
195
196These 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
198section ``[extract_messages]``, and the option names are changed to use
199underscore characters instead of dashes, for example:
200
201.. code-block:: ini
202
203    [extract_messages]
204    keywords = _ gettext ngettext
205    mapping_file = mapping.cfg
206    width = 80
207
208This would be equivalent to invoking the command from the command-line as
209follows::
210
211    $ setup.py extract_messages -k _ -k gettext -k ngettext -F mapping.cfg -w 80
212
213Any path names are interpreted relative to the location of the ``setup.py``
214file. For boolean options, use "true" or "false" values.
215
216
217init_catalog
218============
219
220The ``init_catalog`` command is basically equivalent to the GNU ``msginit``
221program: it creates a new translation catalog based on a PO template file (POT).
222
223If the command has been correctly installed or registered, a project's
224``setup.py`` script should allow you to use the command::
225
226    $ ./setup.py init_catalog --help
227    Global options:
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
232
233    Options for 'init_catalog' command:
234      ...
235
236Running the command will produce a PO file::
237
238    $ ./setup.py init_catalog -l fr -i foobar/locales/messages.pot \
239                             -o foobar/locales/fr/messages.po
240    running init_catalog
241    creating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
242
243
244Options
245-------
246
247The ``init_catalog`` command accepts the following options:
248
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  +-----------------------------+---------------------------------------------+
263
264If ``output-dir`` is specified, but ``output-file`` is not, the default filename
265of the output file will be::
266
267    <output_dir>/<locale>/LC_MESSAGES/<domain>.po
268
269These options can either be specified on the command-line, or in the
270``setup.cfg`` file.
271
272
273update_catalog
274==============
275
276The ``update_catalog`` command is basically equivalent to the GNU ``msgmerge``
277program: it updates an existing translations catalog based on a PO template
278file (POT).
279
280If the command has been correctly installed or registered, a project's
281``setup.py`` script should allow you to use the command::
282
283    $ ./setup.py update_catalog --help
284    Global options:
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
289
290    Options for 'update_catalog' command:
291      ...
292
293Running the command will update a PO file::
294
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'
299
300
301Options
302-------
303
304The ``update_catalog`` command accepts the following options:
305
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 |
321  |                                     | the output                          |
322  +-------------------------------------+-------------------------------------+
323  | ``--no-fuzzy-matching`` (``-N``)    | do not use fuzzy matching           |
324  +-------------------------------------+-------------------------------------+
325  | ``--previous``                      | keep previous msgids of translated  |
326  |                                     | messages                            |
327  +-------------------------------------+-------------------------------------+
328
329If ``output-dir`` is specified, but ``output-file`` is not, the default filename
330of the output file will be::
331
332    <output_dir>/<locale>/LC_MESSAGES/<domain>.po
333
334If neither the ``input_file`` nor the ``locale`` option is set, this command
335looks for all catalog files in the base directory that match the given domain,
336and updates each of them.
337
338These options can either be specified on the command-line, or in the
339``setup.cfg`` file.
340