Mercurial > babel > mirror
view doc/setup.txt @ 91:5cff450b9ed5 trunk
Changed translator comments extraction behaviour in python source code. Match is now true only if the TAG is on the start of the comment. The TAG will also be stripped from the comment. Added a unittest which tests this.
author | palgarvio |
---|---|
date | Mon, 11 Jun 2007 22:27:24 +0000 |
parents | 21e3f63ee8a5 |
children | e1dffa3423a0 |
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.