cmlenz@2: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@2: 
cmlenz@2: ================================
cmlenz@2: Distutils/Setuptools Integration
cmlenz@2: ================================
cmlenz@2: 
cmlenz@2: Babel provides commands for integration into ``setup.py`` scripts, based on
cmlenz@2: either the ``distutils`` package that is part of the Python standard library,
cmlenz@2: or the third-party ``setuptools`` package.
cmlenz@2: 
cmlenz@2: These commands are available by default when Babel has been properly installed,
cmlenz@2: and ``setup.py`` is using ``setuptools``. For projects that use plain old
cmlenz@40: ``distutils``, the commands need to be registered explicitly, for example:
cmlenz@40: 
cmlenz@40: .. code-block:: python
cmlenz@2: 
cmlenz@2:     from distutils.core import setup
cmlenz@54:     from babel.messages import frontend as babel
cmlenz@2:     
cmlenz@2:     setup(
cmlenz@2:         ...
cmlenz@252:         cmdclass = {'compile_catalog': babel.compile_catalog,
cmlenz@252:                     'extract_messages': babel.extract_messages,
cmlenz@252:                     'init_catalog': babel.init_catalog,
cmlenz@252:                     'update_catalog': babel.update_catalog}
cmlenz@2:     )
cmlenz@2: 
cmlenz@2: 
cmlenz@2: .. contents:: Contents
cmlenz@2:    :depth: 2
cmlenz@2: .. sectnum::
cmlenz@2: 
cmlenz@2: 
cmlenz@160: compile_catalog
cmlenz@160: ===============
cmlenz@160: 
cmlenz@160: The ``compile_catalog`` command is similar to the GNU ``msgfmt`` tool, in that
cmlenz@160: it takes a message catalog from a PO file and compiles it to a binary MO file.
cmlenz@160: 
cmlenz@160: If the command has been correctly installed or registered, a project's
cmlenz@160: ``setup.py`` script should allow you to use the command::
cmlenz@160: 
cmlenz@160:     $ ./setup.py compile_catalog --help
cmlenz@160:     Global options:
cmlenz@160:       --verbose (-v)  run verbosely (default)
cmlenz@160:       --quiet (-q)    run quietly (turns verbosity off)
cmlenz@160:       --dry-run (-n)  don't actually do anything
cmlenz@160:       --help (-h)     show detailed help message
cmlenz@160:     
cmlenz@160:     Options for 'compile_catalog' command:
cmlenz@160:        ...
cmlenz@160: 
jruigrok@495: Running the command will produce a binary MO file::
cmlenz@160: 
cmlenz@160:     $ ./setup.py compile_catalog --directory foobar/locale --locale pt_BR
cmlenz@160:     running compile_catalog
jruigrok@495:     compiling catalog to foobar/locale/pt_BR/LC_MESSAGES/messages.mo
cmlenz@160: 
cmlenz@160: 
cmlenz@160: Options
cmlenz@160: -------
cmlenz@160: 
cmlenz@160: The ``compile_catalog`` command accepts the following options:
cmlenz@160: 
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | Option                      | Description                                 |
cmlenz@319:   +=============================+=============================================+
cmlenz@319:   | ``--domain``                | domain of the PO file (defaults to          |
cmlenz@319:   |                             | lower-cased project name)                   |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--directory`` (``-d``)    | name of the base directory                  |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--input-file`` (``-i``)   | name of the input file                      |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--output-file`` (``-o``)  | name of the output file                     |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--locale`` (``-l``)       | locale for the new localized string         |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--use-fuzzy`` (``-f``)    | also include "fuzzy" translations           |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--statistics``            | print statistics about translations         |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@160: 
cmlenz@160: If ``directory`` is specified, but ``output-file`` is not, the default filename
cmlenz@160: of the output file will be::
cmlenz@160: 
cmlenz@177:     <directory>/<locale>/LC_MESSAGES/<domain>.mo
cmlenz@177: 
cmlenz@177: If neither the ``input_file`` nor the ``locale`` option is set, this command
cmlenz@177: looks for all catalog files in the base directory that match the given domain,
cmlenz@177: and compiles each of them to MO files in the same directory.
cmlenz@160: 
cmlenz@160: These options can either be specified on the command-line, or in the
cmlenz@160: ``setup.cfg`` file.
cmlenz@160: 
cmlenz@160: 
cmlenz@2: extract_messages
cmlenz@2: ================
cmlenz@2: 
cmlenz@90: The ``extract_messages`` command is comparable to the GNU ``xgettext`` program:
cmlenz@2: it can extract localizable messages from a variety of difference source files,
cmlenz@2: and generate a PO (portable object) template file from the collected messages.
cmlenz@2: 
cmlenz@160: If the command has been correctly installed or registered, a project's
cmlenz@2: ``setup.py`` script should allow you to use the command::
cmlenz@2: 
cmlenz@2:     $ ./setup.py extract_messages --help
cmlenz@2:     Global options:
cmlenz@2:       --verbose (-v)  run verbosely (default)
cmlenz@2:       --quiet (-q)    run quietly (turns verbosity off)
cmlenz@2:       --dry-run (-n)  don't actually do anything
cmlenz@2:       --help (-h)     show detailed help message
cmlenz@77:     
cmlenz@2:     Options for 'extract_messages' command:
cmlenz@90:        ...
cmlenz@2: 
palgarvio@51: Running the command will produce a PO template file::
cmlenz@2: 
cmlenz@49:     $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
cmlenz@2:     running extract_messages
cmlenz@49:     extracting messages from foobar/__init__.py
cmlenz@49:     extracting messages from foobar/core.py
cmlenz@49:     ...
palgarvio@51:     writing PO template file to foobar/locale/messages.pot
cmlenz@49: 
cmlenz@49: 
cmlenz@49: Method Mapping
cmlenz@49: --------------
cmlenz@49: 
cmlenz@49: The mapping of file patterns to extraction methods (and options) can be
cmlenz@49: specified using a configuration file that is pointed to using the
cmlenz@49: ``--mapping-file`` option shown above. Alternatively, you can configure the
cmlenz@49: mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
cmlenz@49: function:
cmlenz@49: 
cmlenz@49: .. code-block:: python
cmlenz@49: 
cmlenz@49:     setup(...
cmlenz@49:         
cmlenz@49:         message_extractors = {
cmlenz@62:             'foobar': [
cmlenz@117:                 ('**.py',                'python', None),
cmlenz@117:                 ('**/templates/**.html', 'genshi', None),
cmlenz@117:                 ('**/templates/**.txt',  'genshi', {
cmlenz@144:                     'template_class': 'genshi.template:TextTemplate'
cmlenz@62:                 })
cmlenz@62:             ],
cmlenz@49:         },
cmlenz@49:         
cmlenz@49:         ...
cmlenz@49:     )
cmlenz@2: 
cmlenz@2: 
cmlenz@2: Options
cmlenz@2: -------
cmlenz@2: 
cmlenz@90: The ``extract_messages`` command accepts the following options:
cmlenz@2: 
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | Option                      | Description                                  |
cmlenz@49:   +=============================+==============================================+
cmlenz@49:   | ``--charset``               | charset to use in the output file            |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--keywords`` (``-k``)     | space-separated list of keywords to look for |
cmlenz@49:   |                             | in addition to the defaults                  |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--no-default-keywords``   | do not include the default keywords          |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--mapping-file`` (``-F``) | path to the mapping configuration file       |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--no-location``           | do not include location comments with        |
cmlenz@49:   |                             | filename and line number                     |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--omit-header``           | do not include msgid "" entry in header      |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--output-file`` (``-o``)  | name of the output file                      |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--width`` (``-w``)        | set output line width (default 76)           |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--no-wrap``               | do not break long message lines, longer than |
cmlenz@49:   |                             | the output line width, into several lines    |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@62:   | ``--input-dirs``            | directories that should be scanned for       |
cmlenz@62:   |                             | messages                                     |
cmlenz@62:   +-----------------------------+----------------------------------------------+
cmlenz@90:   | ``--sort-output``           | generate sorted output (default False)       |
cmlenz@90:   +-----------------------------+----------------------------------------------+
cmlenz@90:   | ``--sort-by-file``          | sort output by file location (default False) |
cmlenz@90:   +-----------------------------+----------------------------------------------+
cmlenz@90:   | ``--msgid-bugs-address``    | set email address for message bug reports    |
cmlenz@90:   +-----------------------------+----------------------------------------------+
cmlenz@90:   | ``--copyright-holder``      | set copyright holder in output               |
cmlenz@90:   +-----------------------------+----------------------------------------------+
cmlenz@90:   | ``--add-comments (-c)``     | place comment block with TAG (or those       |
cmlenz@90:   |                             | preceding keyword lines) in output file.     |
cmlenz@90:   |                             | Separate multiple TAGs with commas(,)        |
cmlenz@90:   +-----------------------------+----------------------------------------------+
cmlenz@90: 
cmlenz@90: These options can either be specified on the command-line, or in the
cmlenz@90: ``setup.cfg`` file. In the latter case, the options above become entries of the
cmlenz@90: section ``[extract_messages]``, and the option names are changed to use
cmlenz@90: underscore characters instead of dashes, for example:
cmlenz@90: 
cmlenz@90: .. code-block:: ini
cmlenz@90: 
cmlenz@90:     [extract_messages]
pjenvey@554:     keywords = _ gettext ngettext
cmlenz@90:     mapping_file = babel.cfg
cmlenz@90:     width = 80
cmlenz@90: 
cmlenz@90: This would be equivalent to invoking the command from the command-line as
cmlenz@90: follows::
cmlenz@90: 
cmlenz@90:     $ setup.py extract_messages -k _ -k gettext -k ngettext -F mapping.cfg -w 80
cmlenz@90: 
cmlenz@90: Any path names are interpreted relative to the location of the ``setup.py``
cmlenz@90: file. For boolean options, use "true" or "false" values.
cmlenz@90: 
cmlenz@90: 
cmlenz@181: init_catalog
cmlenz@181: ============
cmlenz@90: 
cmlenz@181: The ``init_catalog`` command is basically equivalent to the GNU ``msginit``
cmlenz@90: program: it creates a new translation catalog based on a PO template file (POT).
cmlenz@90: 
cmlenz@160: If the command has been correctly installed or registered, a project's
cmlenz@90: ``setup.py`` script should allow you to use the command::
cmlenz@90: 
cmlenz@181:     $ ./setup.py init_catalog --help
cmlenz@90:     Global options:
cmlenz@90:       --verbose (-v)  run verbosely (default)
cmlenz@90:       --quiet (-q)    run quietly (turns verbosity off)
cmlenz@90:       --dry-run (-n)  don't actually do anything
cmlenz@90:       --help (-h)     show detailed help message
cmlenz@90: 
cmlenz@181:     Options for 'init_catalog' command:
cmlenz@90:       ...
cmlenz@90: 
cmlenz@90: Running the command will produce a PO file::
cmlenz@90: 
cmlenz@181:     $ ./setup.py init_catalog -l fr -i foobar/locales/messages.pot \
cmlenz@90:                              -o foobar/locales/fr/messages.po
cmlenz@181:     running init_catalog
cmlenz@90:     creating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
cmlenz@90: 
cmlenz@90: 
cmlenz@90: Options
cmlenz@90: -------
cmlenz@90: 
cmlenz@181: The ``init_catalog`` command accepts the following options:
cmlenz@90: 
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | Option                      | Description                                 |
cmlenz@319:   +=============================+=============================================+
cmlenz@319:   | ``--domain``                | domain of the PO file (defaults to          |
cmlenz@319:   |                             | lower-cased project name)                   |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--input-file`` (``-i``)   | name of the input file                      |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--output-dir`` (``-d``)   | name of the output directory                |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--output-file`` (``-o``)  | name of the output file                     |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@319:   | ``--locale``                | locale for the new localized string         |
cmlenz@319:   +-----------------------------+---------------------------------------------+
cmlenz@90: 
cmlenz@90: If ``output-dir`` is specified, but ``output-file`` is not, the default filename
cmlenz@90: of the output file will be::
cmlenz@90: 
cmlenz@90:     <output_dir>/<locale>/LC_MESSAGES/<domain>.po
cmlenz@90: 
cmlenz@90: These options can either be specified on the command-line, or in the
cmlenz@90: ``setup.cfg`` file.
cmlenz@181: 
cmlenz@181: 
cmlenz@181: update_catalog
cmlenz@181: ==============
cmlenz@181: 
cmlenz@181: The ``update_catalog`` command is basically equivalent to the GNU ``msgmerge``
cmlenz@181: program: it updates an existing translations catalog based on a PO template
cmlenz@181: file (POT).
cmlenz@181: 
cmlenz@181: If the command has been correctly installed or registered, a project's
cmlenz@181: ``setup.py`` script should allow you to use the command::
cmlenz@181: 
cmlenz@181:     $ ./setup.py update_catalog --help
cmlenz@181:     Global options:
cmlenz@181:       --verbose (-v)  run verbosely (default)
cmlenz@181:       --quiet (-q)    run quietly (turns verbosity off)
cmlenz@181:       --dry-run (-n)  don't actually do anything
cmlenz@181:       --help (-h)     show detailed help message
cmlenz@181: 
cmlenz@181:     Options for 'update_catalog' command:
cmlenz@181:       ...
cmlenz@181: 
cmlenz@181: Running the command will update a PO file::
cmlenz@181: 
cmlenz@181:     $ ./setup.py update_catalog -l fr -i foobar/locales/messages.pot \
cmlenz@181:                                 -o foobar/locales/fr/messages.po
cmlenz@181:     running update_catalog
cmlenz@181:     updating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
cmlenz@181: 
cmlenz@181: 
cmlenz@181: Options
cmlenz@181: -------
cmlenz@181: 
cmlenz@181: The ``update_catalog`` command accepts the following options:
cmlenz@181: 
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@319:   | Option                              | Description                         |
cmlenz@319:   +=====================================+=====================================+
cmlenz@319:   | ``--domain``                        | domain of the PO file (defaults to  |
cmlenz@319:   |                                     | lower-cased project name)           |
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@319:   | ``--input-file`` (``-i``)           | name of the input file              |
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@319:   | ``--output-dir`` (``-d``)           | name of the output directory        |
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@319:   | ``--output-file`` (``-o``)          | name of the output file             |
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@319:   | ``--locale``                        | locale for the new localized string |
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@319:   | ``--ignore-obsolete``               | do not include obsolete messages in |
cmlenz@319:   |                                     | the output                          |
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@319:   | ``--no-fuzzy-matching`` (``-N``)    | do not use fuzzy matching           |
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@319:   | ``--previous``                      | keep previous msgids of translated  |
cmlenz@319:   |                                     | messages                            |
cmlenz@319:   +-------------------------------------+-------------------------------------+
cmlenz@181: 
cmlenz@181: If ``output-dir`` is specified, but ``output-file`` is not, the default filename
cmlenz@181: of the output file will be::
cmlenz@181: 
cmlenz@181:     <output_dir>/<locale>/LC_MESSAGES/<domain>.po
cmlenz@181: 
cmlenz@181: If neither the ``input_file`` nor the ``locale`` option is set, this command
cmlenz@181: looks for all catalog files in the base directory that match the given domain,
cmlenz@181: and updates each of them.
cmlenz@181: 
cmlenz@181: These options can either be specified on the command-line, or in the
cmlenz@181: ``setup.cfg`` file.