Mercurial > babel > old > babel-test
view doc/setup.txt @ 131:a63812008056
Use `dates.format_datetime` for dates in PO(T) header, as `datetime.strftime` produces wrong results on windows.
author | cmlenz |
---|---|
date | Mon, 18 Jun 2007 18:24:44 +0000 |
parents | 41506e62701f |
children | a5914ba672d1 |
line wrap: on
line source
.. -*- mode: rst; encoding: utf-8 -*- ================================ Distutils/Setuptools Integration ================================ Babel provides commands for integration into ``setup.py`` scripts, based on either the ``distutils`` package that is part of the Python standard library, or the third-party ``setuptools`` package. These commands are available by default when Babel has been properly installed, and ``setup.py`` is using ``setuptools``. For projects that use plain old ``distutils``, the commands need to be registered explicitly, for example: .. code-block:: python from distutils.core import setup from babel.messages import frontend as babel setup( ... cmd_class = {'extract_messages': babel.extract_messages, 'new_catalog': babel.new_catalog} ) .. contents:: Contents :depth: 2 .. sectnum:: extract_messages ================ The ``extract_messages`` command is comparable to the GNU ``xgettext`` program: it can extract localizable messages from a variety of difference source files, and generate a PO (portable object) template file from the collected messages. If the command has been correctly installed or registered, another project's ``setup.py`` script should allow you to use the command:: $ ./setup.py extract_messages --help Global options: --verbose (-v) run verbosely (default) --quiet (-q) run quietly (turns verbosity off) --dry-run (-n) don't actually do anything --help (-h) show detailed help message Options for 'extract_messages' command: ... Running the command will produce a PO template file:: $ ./setup.py extract_messages --output-file foobar/locale/messages.pot running extract_messages extracting messages from foobar/__init__.py extracting messages from foobar/core.py ... writing PO template file to foobar/locale/messages.pot Method Mapping -------------- The mapping of file patterns to extraction methods (and options) can be specified using a configuration file that is pointed to using the ``--mapping-file`` option shown above. Alternatively, you can configure the mapping directly in ``setup.py`` using a keyword argument to the ``setup()`` function: .. code-block:: python setup(... message_extractors = { 'foobar': [ ('**.py', 'python', None), ('**/templates/**.html', 'genshi', None), ('**/templates/**.txt', 'genshi', { 'template_class': 'genshi.template.text.TextTemplate' }) ], }, ... ) Options ------- The ``extract_messages`` command accepts the following options: +-----------------------------+----------------------------------------------+ | Option | Description | +=============================+==============================================+ | ``--charset`` | charset to use in the output file | +-----------------------------+----------------------------------------------+ | ``--keywords`` (``-k``) | space-separated list of keywords to look for | | | in addition to the defaults | +-----------------------------+----------------------------------------------+ | ``--no-default-keywords`` | do not include the default keywords | +-----------------------------+----------------------------------------------+ | ``--mapping-file`` (``-F``) | path to the mapping configuration file | +-----------------------------+----------------------------------------------+ | ``--no-location`` | do not include location comments with | | | filename and line number | +-----------------------------+----------------------------------------------+ | ``--omit-header`` | do not include msgid "" entry in header | +-----------------------------+----------------------------------------------+ | ``--output-file`` (``-o``) | name of the output file | +-----------------------------+----------------------------------------------+ | ``--width`` (``-w``) | set output line width (default 76) | +-----------------------------+----------------------------------------------+ | ``--no-wrap`` | do not break long message lines, longer than | | | the output line width, into several lines | +-----------------------------+----------------------------------------------+ | ``--input-dirs`` | directories that should be scanned for | | | messages | +-----------------------------+----------------------------------------------+ | ``--sort-output`` | generate sorted output (default False) | +-----------------------------+----------------------------------------------+ | ``--sort-by-file`` | sort output by file location (default False) | +-----------------------------+----------------------------------------------+ | ``--msgid-bugs-address`` | set email address for message bug reports | +-----------------------------+----------------------------------------------+ | ``--copyright-holder`` | set copyright holder in output | +-----------------------------+----------------------------------------------+ | ``--add-comments (-c)`` | place comment block with TAG (or those | | | preceding keyword lines) in output file. | | | Separate multiple TAGs with commas(,) | +-----------------------------+----------------------------------------------+ These options can either be specified on the command-line, or in the ``setup.cfg`` file. In the latter case, the options above become entries of the section ``[extract_messages]``, and the option names are changed to use underscore characters instead of dashes, for example: .. code-block:: ini [extract_messages] keywords = _, gettext, ngettext mapping_file = babel.cfg width = 80 This would be equivalent to invoking the command from the command-line as follows:: $ setup.py extract_messages -k _ -k gettext -k ngettext -F mapping.cfg -w 80 Any path names are interpreted relative to the location of the ``setup.py`` file. For boolean options, use "true" or "false" values. new_catalog =========== The ``new_catalog`` command is basically equivalent to the GNU ``msginit`` program: it creates a new translation catalog based on a PO template file (POT). If the command has been correctly installed or registered, another project's ``setup.py`` script should allow you to use the command:: $ ./setup.py new_catalog --help Global options: --verbose (-v) run verbosely (default) --quiet (-q) run quietly (turns verbosity off) --dry-run (-n) don't actually do anything --help (-h) show detailed help message Options for 'new_catalog' command: ... Running the command will produce a PO file:: $ ./setup.py new_catalog -l fr -i foobar/locales/messages.pot \ -o foobar/locales/fr/messages.po running new_catalog creating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot' Options ------- The ``new_catalog`` command accepts the following options: +-----------------------------+----------------------------------------------+ | Option | Description | +=============================+==============================================+ | ``--domain`` | domain of the PO file (defaults to | | | lower-cased project name) | +-----------------------------+----------------------------------------------+ | ``--input-file`` (``-i``) | name of the input file | +-----------------------------+----------------------------------------------+ | ``--output-dir`` (``-d``) | name of the output directory | +-----------------------------+----------------------------------------------+ | ``--output-file`` (``-o``) | name of the output file | +-----------------------------+----------------------------------------------+ | ``--locale`` | locale for the new localized string | +-----------------------------+----------------------------------------------+ | ``--omit-header`` | do not include msgid "" entry in header | +-----------------------------+----------------------------------------------+ | ``--first-author`` | name of the first author | +-----------------------------+----------------------------------------------+ | ``--first-author-email`` | email address of the first author | +-----------------------------+----------------------------------------------+ If ``output-dir`` is specified, but ``output-file`` is not, the default filename of the output file will be:: <output_dir>/<locale>/LC_MESSAGES/<domain>.po These options can either be specified on the command-line, or in the ``setup.cfg`` file.