Mercurial > babel > old > mirror

annotate doc/setup.txt @ 79:7cf16a49e8b2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated frontend screens for added sorting features.
author cmlenz
date Fri, 08 Jun 2007 23:27:35 +0000
parents 7eb6fea17864
children 8e2e9d549693
rev   line source
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
3 ================================
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
4 Distutils/Setuptools Integration
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
5 ================================
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7 Babel provides commands for integration into ``setup.py`` scripts, based on
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 either the ``distutils`` package that is part of the Python standard library,
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 or the third-party ``setuptools`` package.
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11 These commands are available by default when Babel has been properly installed,
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12 and ``setup.py`` is using ``setuptools``. For projects that use plain old
42
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
13 ``distutils``, the commands need to be registered explicitly, for example:
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
14
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
15 .. code-block:: python
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
16
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
17 from distutils.core import setup
56
27d55a07c897 Rename the `babel.catalog` package to `babel.messages` for consistency with the other package names.
cmlenz
parents: 53
diff changeset
18 from babel.messages import frontend as babel
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
19
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
20 setup(
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
21 ...
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
22 cmd_class = {'extract_messages': babel.extract_messages}
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
23 )
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
24
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
25
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
26 .. contents:: Contents
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
27 :depth: 2
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
28 .. sectnum::
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
29
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
30
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
31 extract_messages
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
32 ================
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
33
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
34 The ``extract_messages`` command is comparabe to the GNU ``xgettext`` program:
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
35 it can extract localizable messages from a variety of difference source files,
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
36 and generate a PO (portable object) template file from the collected messages.
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
37
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
38 If the command has been correctly installed or registered, another project's
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
39 ``setup.py`` script should allow you to use the command::
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
40
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
41 $ ./setup.py extract_messages --help
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
42 Global options:
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
43 --verbose (-v) run verbosely (default)
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
44 --quiet (-q) run quietly (turns verbosity off)
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
45 --dry-run (-n) don't actually do anything
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
46 --help (-h) show detailed help message
79
7cf16a49e8b2 Updated frontend screens for added sorting features.
cmlenz
parents: 64
diff changeset
47
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
48 Options for 'extract_messages' command:
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
49 --charset charset to use in the output file
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
50 --keywords (-k) space-separated list of keywords to look for in
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
51 addition to the defaults
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
52 --no-default-keywords do not include the default keywords
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
53 --mapping-file (-F) path to the mapping configuration file
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
54 --no-location do not include location comments with filename and
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
55 line number
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
56 --omit-header do not include msgid "" entry in header
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
57 --output-file (-o) name of the output file
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
58 --width (-w) set output line width (default 76)
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
59 --no-wrap do not break long message lines, longer than the
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
60 output line width, into several lines
79
7cf16a49e8b2 Updated frontend screens for added sorting features.
cmlenz
parents: 64
diff changeset
61 --sort-output generate sorted output (default False)
7cf16a49e8b2 Updated frontend screens for added sorting features.
cmlenz
parents: 64
diff changeset
62 --sort-by-file sort output by file location (default False)
64
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
63 --input-dirs directories that should be scanned for messages
79
7cf16a49e8b2 Updated frontend screens for added sorting features.
cmlenz
parents: 64
diff changeset
64
7cf16a49e8b2 Updated frontend screens for added sorting features.
cmlenz
parents: 64
diff changeset
65 usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
7cf16a49e8b2 Updated frontend screens for added sorting features.
cmlenz
parents: 64
diff changeset
66 or: setup.py --help [cmd1 cmd2 ...]
7cf16a49e8b2 Updated frontend screens for added sorting features.
cmlenz
parents: 64
diff changeset
67 or: setup.py --help-commands
7cf16a49e8b2 Updated frontend screens for added sorting features.
cmlenz
parents: 64
diff changeset
68 or: setup.py cmd --help
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
69
53
52dbebdd3789 Fixed a bug regarding plural msgid's handling when writing the `.pot` file.
palgarvio
parents: 51
diff changeset
70 Running the command will produce a PO template file::
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
71
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
72 $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
73 running extract_messages
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
74 extracting messages from foobar/__init__.py
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
75 extracting messages from foobar/core.py
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
76 ...
53
52dbebdd3789 Fixed a bug regarding plural msgid's handling when writing the `.pot` file.
palgarvio
parents: 51
diff changeset
77 writing PO template file to foobar/locale/messages.pot
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
78
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
79
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
80 Method Mapping
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
81 --------------
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
82
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
83 The mapping of file patterns to extraction methods (and options) can be
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
84 specified using a configuration file that is pointed to using the
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
85 ``--mapping-file`` option shown above. Alternatively, you can configure the
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
86 mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
87 function:
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
88
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
89 .. code-block:: python
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
90
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
91 setup(...
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
92
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
93 message_extractors = {
64
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
94 'foobar': [
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
95 ('**.py', ('python', None),
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
96 ('**/templates/**.html', ('genshi', None),
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
97 ('**/templates/**.txt', ('genshi', {
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
98 'template_class': 'genshi.template.text.TextTemplate'
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
99 })
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
100 ],
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
101 },
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
102
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
103 ...
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
104 )
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
105
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
106
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
107 Options
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
108 -------
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
109
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
110 As shown in the ``--help`` output above, the ``extract_messages`` command
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
111 accepts the following options:
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
112
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
113 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
114 | Option | Description |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
115 +=============================+==============================================+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
116 | ``--charset`` | charset to use in the output file |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
117 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
118 | ``--keywords`` (``-k``) | space-separated list of keywords to look for |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
119 | | in addition to the defaults |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
120 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
121 | ``--no-default-keywords`` | do not include the default keywords |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
122 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
123 | ``--mapping-file`` (``-F``) | path to the mapping configuration file |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
124 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
125 | ``--no-location`` | do not include location comments with |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
126 | | filename and line number |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
127 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
128 | ``--omit-header`` | do not include msgid "" entry in header |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
129 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
130 | ``--output-file`` (``-o``) | name of the output file |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
131 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
132 | ``--width`` (``-w``) | set output line width (default 76) |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
133 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
134 | ``--no-wrap`` | do not break long message lines, longer than |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
135 | | the output line width, into several lines |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
136 +-----------------------------+----------------------------------------------+
64
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
137 | ``--input-dirs`` | directories that should be scanned for |
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
138 | | messages |
7eb6fea17864 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 56
diff changeset
139 +-----------------------------+----------------------------------------------+
Copyright (C) 2012-2017 Edgewall Software