Mercurial > babel > old > mirror
diff 0.8.x/doc/setup.txt @ 142:4a7af44e6695 stable
Create branch for 0.8.x releases.
author | cmlenz |
---|---|
date | Wed, 20 Jun 2007 10:09:07 +0000 |
parents | |
children | 32a242175da5 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/0.8.x/doc/setup.txt @@ -0,0 +1,214 @@ +.. -*- 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.