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