Mercurial > babel > mirror
diff doc/setup.txt @ 2:20896f1e91c6 trunk
Forgot to check in the doc directory.
author | cmlenz |
---|---|
date | Wed, 30 May 2007 07:37:26 +0000 |
parents | |
children | 0739bc8e7210 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/doc/setup.txt @@ -0,0 +1,78 @@ +.. -*- 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:: + + from distutils.core import setup + from babel.catalog import frontend as babel + + setup( + ... + cmd_class = {'extract_messages': babel.extract_messages} + ) + + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +extract_messages +================ + +The ``extract_messages`` command is comparabe 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: + --charset charset to use in the output + --keywords (-k) comma-separated list of keywords to look for in addition + to the defaults + --no-location do not write filename/lineno location comments + --output-file filename of the output PO file + +Running the command will produce a PO file:: + + $ ./setup.py extract_messages --output-file webapp/locales/messages.pot + running extract_messages + extracting messages from 'webapp' + extracting messages from 'webparts' + writing PO file to webapp/locales/messages.pot + + +Options +------- + +As shown in the ``--help`` output above, the ``extract_messages`` command +accepts the following options: + +``--charset`` + The character set / encoding to use in the generated PO file. +``--keywords`` + A comma-separated list of keywords (function names) to look for in addition + to the default keywords +``--no-location`` + If this flag is set, location comments will not be included in the generated + PO file. +``--output-file`` or ``-o`` + The path to the PO file that should be generated +