Mercurial > babel > mirror
annotate doc/setup.txt @ 87:72c7ac384609 trunk
Fixed a bug on Catalog. `__setitem__` was not updating the translator comments. Thanks pjenvey!
Fixed a bug on the `new_catalog` and `init` frontends, we were badly building the new directory for the localized catalog. Normal directory hierarchy is `<output_dir>/<locale>/LC_MESSAGES/<domain>.po`, not `<output_dir>/<locale>/<domain>.po`, ie `LC_MESSAGES/<locale>/<domain>.po`.
author | palgarvio |
---|---|
date | Mon, 11 Jun 2007 00:48:07 +0000 |
parents | 116e34b8cefa |
children | 21e3f63ee8a5 |
rev | line source |
---|---|
2 | 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 | |
40 | 13 ``distutils``, the commands need to be registered explicitly, for example: |
14 | |
15 .. code-block:: python | |
2 | 16 |
17 from distutils.core import setup | |
54
7dbcbc3f07e0
Rename the `babel.catalog` package to `babel.messages` for consistency with the other package names.
cmlenz
parents:
51
diff
changeset
|
18 from babel.messages import frontend as babel |
2 | 19 |
20 setup( | |
21 ... | |
22 cmd_class = {'extract_messages': babel.extract_messages} | |
23 ) | |
24 | |
25 | |
26 .. contents:: Contents | |
27 :depth: 2 | |
28 .. sectnum:: | |
29 | |
30 | |
31 extract_messages | |
32 ================ | |
33 | |
34 The ``extract_messages`` command is comparabe to the GNU ``xgettext`` program: | |
35 it can extract localizable messages from a variety of difference source files, | |
36 and generate a PO (portable object) template file from the collected messages. | |
37 | |
38 If the command has been correctly installed or registered, another project's | |
39 ``setup.py`` script should allow you to use the command:: | |
40 | |
41 $ ./setup.py extract_messages --help | |
42 Global options: | |
43 --verbose (-v) run verbosely (default) | |
44 --quiet (-q) run quietly (turns verbosity off) | |
45 --dry-run (-n) don't actually do anything | |
46 --help (-h) show detailed help message | |
77 | 47 |
2 | 48 Options for 'extract_messages' command: |
49
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
49 --charset charset to use in the output file |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
50 --keywords (-k) space-separated list of keywords to look for in |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
51 addition to the defaults |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
52 --no-default-keywords do not include the default keywords |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
53 --mapping-file (-F) path to the mapping configuration file |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
54 --no-location do not include location comments with filename and |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
55 line number |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
56 --omit-header do not include msgid "" entry in header |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
57 --output-file (-o) name of the output file |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
58 --width (-w) set output line width (default 76) |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
59 --no-wrap do not break long message lines, longer than the |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
60 output line width, into several lines |
77 | 61 --sort-output generate sorted output (default False) |
62 --sort-by-file sort output by file location (default False) | |
78
d0d8d6cd8601
Fixed the plurals header on `Catalog` which should only be written if it's not a catalog template.
palgarvio
parents:
77
diff
changeset
|
63 --msgid-bugs-address set report address for msgid |
79
450ac2291ca5
Implemented item 4 from #12. Set the copyright holder in the output.
palgarvio
parents:
78
diff
changeset
|
64 --copyright-holder set copyright holder in output |
80
116e34b8cefa
Added support for translator comments at the API and frontends levels.(See #12, item 1). Updated docs and tests accordingly.
palgarvio
parents:
79
diff
changeset
|
65 --add-comments (-c) place comment block with TAG (or those preceding |
116e34b8cefa
Added support for translator comments at the API and frontends levels.(See #12, item 1). Updated docs and tests accordingly.
palgarvio
parents:
79
diff
changeset
|
66 keyword lines) in output file. Seperate multiple TAGs |
116e34b8cefa
Added support for translator comments at the API and frontends levels.(See #12, item 1). Updated docs and tests accordingly.
palgarvio
parents:
79
diff
changeset
|
67 with commas(,) |
62
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
68 --input-dirs directories that should be scanned for messages |
77 | 69 |
70 usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...] | |
71 or: setup.py --help [cmd1 cmd2 ...] | |
72 or: setup.py --help-commands | |
73 or: setup.py cmd --help | |
2 | 74 |
51
d484eb9a70d5
Fixed a bug regarding plural msgid's handling when writing the `.pot` file.
palgarvio
parents:
49
diff
changeset
|
75 Running the command will produce a PO template file:: |
2 | 76 |
49
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
77 $ ./setup.py extract_messages --output-file foobar/locale/messages.pot |
2 | 78 running extract_messages |
49
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
79 extracting messages from foobar/__init__.py |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
80 extracting messages from foobar/core.py |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
81 ... |
51
d484eb9a70d5
Fixed a bug regarding plural msgid's handling when writing the `.pot` file.
palgarvio
parents:
49
diff
changeset
|
82 writing PO template file to foobar/locale/messages.pot |
49
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
83 |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
84 |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
85 Method Mapping |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
86 -------------- |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
87 |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
88 The mapping of file patterns to extraction methods (and options) can be |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
89 specified using a configuration file that is pointed to using the |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
90 ``--mapping-file`` option shown above. Alternatively, you can configure the |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
91 mapping directly in ``setup.py`` using a keyword argument to the ``setup()`` |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
92 function: |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
93 |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
94 .. code-block:: python |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
95 |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
96 setup(... |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
97 |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
98 message_extractors = { |
62
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
99 'foobar': [ |
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
100 ('**.py', ('python', None), |
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
101 ('**/templates/**.html', ('genshi', None), |
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
102 ('**/templates/**.txt', ('genshi', { |
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
103 'template_class': 'genshi.template.text.TextTemplate' |
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
104 }) |
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
105 ], |
49
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
106 }, |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
107 |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
108 ... |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
109 ) |
2 | 110 |
111 | |
112 Options | |
113 ------- | |
114 | |
115 As shown in the ``--help`` output above, the ``extract_messages`` command | |
116 accepts the following options: | |
117 | |
49
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
118 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
119 | Option | Description | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
120 +=============================+==============================================+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
121 | ``--charset`` | charset to use in the output file | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
122 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
123 | ``--keywords`` (``-k``) | space-separated list of keywords to look for | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
124 | | in addition to the defaults | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
125 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
126 | ``--no-default-keywords`` | do not include the default keywords | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
127 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
128 | ``--mapping-file`` (``-F``) | path to the mapping configuration file | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
129 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
130 | ``--no-location`` | do not include location comments with | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
131 | | filename and line number | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
132 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
133 | ``--omit-header`` | do not include msgid "" entry in header | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
134 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
135 | ``--output-file`` (``-o``) | name of the output file | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
136 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
137 | ``--width`` (``-w``) | set output line width (default 76) | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
138 +-----------------------------+----------------------------------------------+ |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
139 | ``--no-wrap`` | do not break long message lines, longer than | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
140 | | the output line width, into several lines | |
37bd476dafe4
Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents:
40
diff
changeset
|
141 +-----------------------------+----------------------------------------------+ |
62
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
142 | ``--input-dirs`` | directories that should be scanned for | |
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
143 | | messages | |
2df27f49c320
The order of extraction methods is now preserved (see #10).
cmlenz
parents:
54
diff
changeset
|
144 +-----------------------------+----------------------------------------------+ |