Mercurial > babel > old > mirror

annotate doc/setup.txt @ 53:52dbebdd3789

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed a bug regarding plural msgid's handling when writing the `.pot` file. Renamed old `write_po` to `write_pot` which is what it actually does and also adds space to the new `write_po`. Changed tests accordingly. Added support to create new localized catalogs from a catalog template, `write_po`..
author palgarvio
date Thu, 07 Jun 2007 22:48:47 +0000
parents 3664c93860f1
children 27d55a07c897
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
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
18 from babel.catalog import frontend as babel
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
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
47
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
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
61
53
52dbebdd3789 Fixed a bug regarding plural msgid's handling when writing the `.pot` file.
palgarvio
parents: 51
diff changeset
62 Running the command will produce a PO template file::
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
63
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
64 $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
65 running extract_messages
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
66 extracting messages from foobar/__init__.py
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
67 extracting messages from foobar/core.py
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
68 ...
53
52dbebdd3789 Fixed a bug regarding plural msgid's handling when writing the `.pot` file.
palgarvio
parents: 51
diff changeset
69 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
70
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
71
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
72 Method Mapping
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
73 --------------
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
74
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
75 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
76 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
77 ``--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
78 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
79 function:
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
80
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
81 .. code-block:: python
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 setup(...
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
84
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
85 message_extractors = {
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
86 'foobar/**.py': ('python', None),
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
87 'foobar/**/templates/**.html': ('genshi', None),
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
88 'foobar/**/templates/**.txt': ('genshi', {
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
89 'template_class': 'genshi.template.text.TextTemplate'
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 },
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 ...
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
94 )
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
95
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
96
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
97 Options
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
98 -------
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
99
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
100 As shown in the ``--help`` output above, the ``extract_messages`` command
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
101 accepts the following options:
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
102
51
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 | Option | Description |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
105 +=============================+==============================================+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
106 | ``--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
107 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
108 | ``--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
109 | | in addition to the defaults |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
110 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
111 | ``--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
112 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
113 | ``--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
114 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
115 | ``--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
116 | | filename and line number |
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 | ``--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
119 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
120 | ``--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
121 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
122 | ``--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
123 +-----------------------------+----------------------------------------------+
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
124 | ``--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
125 | | the output line width, into several lines |
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 42
diff changeset
126 +-----------------------------+----------------------------------------------+
Copyright (C) 2012-2017 Edgewall Software