Mercurial > babel > old > mirror
comparison 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 |
comparison
equal
deleted
inserted
replaced
| 1:bf36ec5f5e50 | 142:4a7af44e6695 |
|---|---|
| 1 .. -*- mode: rst; encoding: utf-8 -*- | |
| 2 | |
| 3 ================================ | |
| 4 Distutils/Setuptools Integration | |
| 5 ================================ | |
| 6 | |
| 7 Babel provides commands for integration into ``setup.py`` scripts, based on | |
| 8 either the ``distutils`` package that is part of the Python standard library, | |
| 9 or the third-party ``setuptools`` package. | |
| 10 | |
| 11 These commands are available by default when Babel has been properly installed, | |
| 12 and ``setup.py`` is using ``setuptools``. For projects that use plain old | |
| 13 ``distutils``, the commands need to be registered explicitly, for example: | |
| 14 | |
| 15 .. code-block:: python | |
| 16 | |
| 17 from distutils.core import setup | |
| 18 from babel.messages import frontend as babel | |
| 19 | |
| 20 setup( | |
| 21 ... | |
| 22 cmd_class = {'extract_messages': babel.extract_messages, | |
| 23 'new_catalog': babel.new_catalog} | |
| 24 ) | |
| 25 | |
| 26 | |
| 27 .. contents:: Contents | |
| 28 :depth: 2 | |
| 29 .. sectnum:: | |
| 30 | |
| 31 | |
| 32 extract_messages | |
| 33 ================ | |
| 34 | |
| 35 The ``extract_messages`` command is comparable to the GNU ``xgettext`` program: | |
| 36 it can extract localizable messages from a variety of difference source files, | |
| 37 and generate a PO (portable object) template file from the collected messages. | |
| 38 | |
| 39 If the command has been correctly installed or registered, another project's | |
| 40 ``setup.py`` script should allow you to use the command:: | |
| 41 | |
| 42 $ ./setup.py extract_messages --help | |
| 43 Global options: | |
| 44 --verbose (-v) run verbosely (default) | |
| 45 --quiet (-q) run quietly (turns verbosity off) | |
| 46 --dry-run (-n) don't actually do anything | |
| 47 --help (-h) show detailed help message | |
| 48 | |
| 49 Options for 'extract_messages' command: | |
| 50 ... | |
| 51 | |
| 52 Running the command will produce a PO template file:: | |
| 53 | |
| 54 $ ./setup.py extract_messages --output-file foobar/locale/messages.pot | |
| 55 running extract_messages | |
| 56 extracting messages from foobar/__init__.py | |
| 57 extracting messages from foobar/core.py | |
| 58 ... | |
| 59 writing PO template file to foobar/locale/messages.pot | |
| 60 | |
| 61 | |
| 62 Method Mapping | |
| 63 -------------- | |
| 64 | |
| 65 The mapping of file patterns to extraction methods (and options) can be | |
| 66 specified using a configuration file that is pointed to using the | |
| 67 ``--mapping-file`` option shown above. Alternatively, you can configure the | |
| 68 mapping directly in ``setup.py`` using a keyword argument to the ``setup()`` | |
| 69 function: | |
| 70 | |
| 71 .. code-block:: python | |
| 72 | |
| 73 setup(... | |
| 74 | |
| 75 message_extractors = { | |
| 76 'foobar': [ | |
| 77 ('**.py', 'python', None), | |
| 78 ('**/templates/**.html', 'genshi', None), | |
| 79 ('**/templates/**.txt', 'genshi', { | |
| 80 'template_class': 'genshi.template.text.TextTemplate' | |
| 81 }) | |
| 82 ], | |
| 83 }, | |
| 84 | |
| 85 ... | |
| 86 ) | |
| 87 | |
| 88 | |
| 89 Options | |
| 90 ------- | |
| 91 | |
| 92 The ``extract_messages`` command accepts the following options: | |
| 93 | |
| 94 +-----------------------------+----------------------------------------------+ | |
| 95 | Option | Description | | |
| 96 +=============================+==============================================+ | |
| 97 | ``--charset`` | charset to use in the output file | | |
| 98 +-----------------------------+----------------------------------------------+ | |
| 99 | ``--keywords`` (``-k``) | space-separated list of keywords to look for | | |
| 100 | | in addition to the defaults | | |
| 101 +-----------------------------+----------------------------------------------+ | |
| 102 | ``--no-default-keywords`` | do not include the default keywords | | |
| 103 +-----------------------------+----------------------------------------------+ | |
| 104 | ``--mapping-file`` (``-F``) | path to the mapping configuration file | | |
| 105 +-----------------------------+----------------------------------------------+ | |
| 106 | ``--no-location`` | do not include location comments with | | |
| 107 | | filename and line number | | |
| 108 +-----------------------------+----------------------------------------------+ | |
| 109 | ``--omit-header`` | do not include msgid "" entry in header | | |
| 110 +-----------------------------+----------------------------------------------+ | |
| 111 | ``--output-file`` (``-o``) | name of the output file | | |
| 112 +-----------------------------+----------------------------------------------+ | |
| 113 | ``--width`` (``-w``) | set output line width (default 76) | | |
| 114 +-----------------------------+----------------------------------------------+ | |
| 115 | ``--no-wrap`` | do not break long message lines, longer than | | |
| 116 | | the output line width, into several lines | | |
| 117 +-----------------------------+----------------------------------------------+ | |
| 118 | ``--input-dirs`` | directories that should be scanned for | | |
| 119 | | messages | | |
| 120 +-----------------------------+----------------------------------------------+ | |
| 121 | ``--sort-output`` | generate sorted output (default False) | | |
| 122 +-----------------------------+----------------------------------------------+ | |
| 123 | ``--sort-by-file`` | sort output by file location (default False) | | |
| 124 +-----------------------------+----------------------------------------------+ | |
| 125 | ``--msgid-bugs-address`` | set email address for message bug reports | | |
| 126 +-----------------------------+----------------------------------------------+ | |
| 127 | ``--copyright-holder`` | set copyright holder in output | | |
| 128 +-----------------------------+----------------------------------------------+ | |
| 129 | ``--add-comments (-c)`` | place comment block with TAG (or those | | |
| 130 | | preceding keyword lines) in output file. | | |
| 131 | | Separate multiple TAGs with commas(,) | | |
| 132 +-----------------------------+----------------------------------------------+ | |
| 133 | |
| 134 These options can either be specified on the command-line, or in the | |
| 135 ``setup.cfg`` file. In the latter case, the options above become entries of the | |
| 136 section ``[extract_messages]``, and the option names are changed to use | |
| 137 underscore characters instead of dashes, for example: | |
| 138 | |
| 139 .. code-block:: ini | |
| 140 | |
| 141 [extract_messages] | |
| 142 keywords = _, gettext, ngettext | |
| 143 mapping_file = babel.cfg | |
| 144 width = 80 | |
| 145 | |
| 146 This would be equivalent to invoking the command from the command-line as | |
| 147 follows:: | |
| 148 | |
| 149 $ setup.py extract_messages -k _ -k gettext -k ngettext -F mapping.cfg -w 80 | |
| 150 | |
| 151 Any path names are interpreted relative to the location of the ``setup.py`` | |
| 152 file. For boolean options, use "true" or "false" values. | |
| 153 | |
| 154 | |
| 155 new_catalog | |
| 156 =========== | |
| 157 | |
| 158 The ``new_catalog`` command is basically equivalent to the GNU ``msginit`` | |
| 159 program: it creates a new translation catalog based on a PO template file (POT). | |
| 160 | |
| 161 If the command has been correctly installed or registered, another project's | |
| 162 ``setup.py`` script should allow you to use the command:: | |
| 163 | |
| 164 $ ./setup.py new_catalog --help | |
| 165 Global options: | |
| 166 --verbose (-v) run verbosely (default) | |
| 167 --quiet (-q) run quietly (turns verbosity off) | |
| 168 --dry-run (-n) don't actually do anything | |
| 169 --help (-h) show detailed help message | |
| 170 | |
| 171 Options for 'new_catalog' command: | |
| 172 ... | |
| 173 | |
| 174 Running the command will produce a PO file:: | |
| 175 | |
| 176 $ ./setup.py new_catalog -l fr -i foobar/locales/messages.pot \ | |
| 177 -o foobar/locales/fr/messages.po | |
| 178 running new_catalog | |
| 179 creating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot' | |
| 180 | |
| 181 | |
| 182 Options | |
| 183 ------- | |
| 184 | |
| 185 The ``new_catalog`` command accepts the following options: | |
| 186 | |
| 187 +-----------------------------+----------------------------------------------+ | |
| 188 | Option | Description | | |
| 189 +=============================+==============================================+ | |
| 190 | ``--domain`` | domain of the PO file (defaults to | | |
| 191 | | lower-cased project name) | | |
| 192 +-----------------------------+----------------------------------------------+ | |
| 193 | ``--input-file`` (``-i``) | name of the input file | | |
| 194 +-----------------------------+----------------------------------------------+ | |
| 195 | ``--output-dir`` (``-d``) | name of the output directory | | |
| 196 +-----------------------------+----------------------------------------------+ | |
| 197 | ``--output-file`` (``-o``) | name of the output file | | |
| 198 +-----------------------------+----------------------------------------------+ | |
| 199 | ``--locale`` | locale for the new localized string | | |
| 200 +-----------------------------+----------------------------------------------+ | |
| 201 | ``--omit-header`` | do not include msgid "" entry in header | | |
| 202 +-----------------------------+----------------------------------------------+ | |
| 203 | ``--first-author`` | name of the first author | | |
| 204 +-----------------------------+----------------------------------------------+ | |
| 205 | ``--first-author-email`` | email address of the first author | | |
| 206 +-----------------------------+----------------------------------------------+ | |
| 207 | |
| 208 If ``output-dir`` is specified, but ``output-file`` is not, the default filename | |
| 209 of the output file will be:: | |
| 210 | |
| 211 <output_dir>/<locale>/LC_MESSAGES/<domain>.po | |
| 212 | |
| 213 These options can either be specified on the command-line, or in the | |
| 214 ``setup.cfg`` file. |