Mercurial > babel > mirror

annotate doc/setup.txt @ 80:116e34b8cefa trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added support for translator comments at the API and frontends levels.(See #12, item 1). Updated docs and tests accordingly.
author palgarvio
date Sun, 10 Jun 2007 14:21:01 +0000
parents 450ac2291ca5
children 21e3f63ee8a5
rev   line source
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
3 ================================
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
4 Distutils/Setuptools Integration
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
5 ================================
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7 Babel provides commands for integration into ``setup.py`` scripts, based on
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 either the ``distutils`` package that is part of the Python standard library,
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 or the third-party ``setuptools`` package.
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11 These commands are available by default when Babel has been properly installed,
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12 and ``setup.py`` is using ``setuptools``. For projects that use plain old
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
13 ``distutils``, the commands need to be registered explicitly, for example:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
14
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
15 .. code-block:: python
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
16
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
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
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
19
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
20 setup(
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
21 ...
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
22 cmd_class = {'extract_messages': babel.extract_messages}
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
23 )
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
24
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
25
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
26 .. contents:: Contents
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
27 :depth: 2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
28 .. sectnum::
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
29
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
30
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
31 extract_messages
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
32 ================
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
33
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
34 The ``extract_messages`` command is comparabe to the GNU ``xgettext`` program:
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
35 it can extract localizable messages from a variety of difference source files,
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
36 and generate a PO (portable object) template file from the collected messages.
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
37
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
38 If the command has been correctly installed or registered, another project's
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
39 ``setup.py`` script should allow you to use the command::
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
40
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
41 $ ./setup.py extract_messages --help
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
42 Global options:
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
43 --verbose (-v) run verbosely (default)
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
44 --quiet (-q) run quietly (turns verbosity off)
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
45 --dry-run (-n) don't actually do anything
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
46 --help (-h) show detailed help message
77
c75fa55a65b9 Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
47
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
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
c75fa55a65b9 Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
61 --sort-output generate sorted output (default False)
c75fa55a65b9 Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
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
c75fa55a65b9 Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
69
c75fa55a65b9 Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
70 usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
c75fa55a65b9 Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
71 or: setup.py --help [cmd1 cmd2 ...]
c75fa55a65b9 Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
72 or: setup.py --help-commands
c75fa55a65b9 Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
73 or: setup.py cmd --help
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
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
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
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
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
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
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
110
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
111
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
112 Options
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
113 -------
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
114
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
115 As shown in the ``--help`` output above, the ``extract_messages`` command
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
116 accepts the following options:
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
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 +-----------------------------+----------------------------------------------+
Copyright (C) 2012-2017 Edgewall Software