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. |