Mercurial > babel > old > mirror

annotate doc/messages.txt @ 555:4ed1a17bff27

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add mention of javascript builtin extractor.
author jruigrok
date Fri, 22 Apr 2011 12:53:30 +0000
parents 89292e10bd25
children
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 Working with Message Catalogs
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 .. contents:: Contents
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
8 :depth: 3
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 .. sectnum::
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
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12 Introduction
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
13 ============
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
14
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
15 The ``gettext`` translation system enables you to mark any strings used in your
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
16 application as subject to localization, by wrapping them in functions such as
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
17 ``gettext(str)`` and ``ngettext(singular, plural, num)``. For brevity, the
42
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
18 ``gettext`` function is often aliased to ``_(str)``, so you can write:
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
19
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
20 .. code-block:: python
4
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 print _("Hello")
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
23
42
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
24 instead of just:
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
25
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
26 .. code-block:: python
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
27
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
28 print "Hello"
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 to make the string "Hello" localizable.
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
31
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
32 Message catalogs are collections of translations for such localizable messages
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
33 used in an application. They are commonly stored in PO (Portable Object) and MO
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
34 (Machine Object) files, the formats of which are defined by the GNU `gettext`_
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
35 tools and the GNU `translation project`_.
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
36
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
37 .. _`gettext`: http://www.gnu.org/software/gettext/
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
38 .. _`translation project`: http://sourceforge.net/projects/translation
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
39
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
40 The general procedure for building message catalogs looks something like this:
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
41
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
42 * use a tool (such as ``xgettext``) to extract localizable strings from the
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
43 code base and write them to a POT (PO Template) file.
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
44 * make a copy of the POT file for a specific locale (for example, "en_US")
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
45 and start translating the messages
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
46 * use a tool such as ``msgfmt`` to compile the locale PO file into an binary
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
47 MO file
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
48 * later, when code changes make it necessary to update the translations, you
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
49 regenerate the POT file and merge the changes into the various
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
50 locale-specific PO files, for example using ``msgmerge``
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
51
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
52 Python provides the `gettext module`_ as part of the standard library, which
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
53 enables applications to work with appropriately generated MO files.
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
54
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
55 .. _`gettext module`: http://docs.python.org/lib/module-gettext.html
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
56
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
57 As ``gettext`` provides a solid and well supported foundation for translating
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
58 application messages, Babel does not reinvent the wheel, but rather reuses this
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
59 infrastructure, and makes it easier to build message catalogs for Python
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
60 applications.
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
61
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
62
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
63 Message Extraction
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
64 ==================
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
65
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
66 Babel provides functionality similar to that of the ``xgettext`` program,
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
67 except that only extraction from Python source files is built-in, while support
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
68 for other file formats can be added using a simple extension mechanism.
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
69
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
70 Unlike ``xgettext``, which is usually invoked once for every file, the routines
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
71 for message extraction in Babel operate on directories. While the per-file
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
72 approach of ``xgettext`` works nicely with projects using a ``Makefile``,
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
73 Python projects rarely use ``make``, and thus a different mechanism is needed
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
74 for extracting messages from the heterogeneous collection of source files that
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
75 many Python projects are composed of.
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
76
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
77 When message extraction is based on directories instead of individual files,
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
78 there needs to be a way to configure which files should be treated in which
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
79 manner. For example, while many projects may contain ``.html`` files, some of
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
80 those files may be static HTML files that don't contain localizable message,
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
81 while others may be `Django`_ templates, and still others may contain `Genshi`_
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
82 markup templates. Some projects may even mix HTML files for different templates
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
83 languages (for whatever reason). Therefore the way in which messages are
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
84 extracted from source files can not only depend on the file extension, but
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
85 needs to be controllable in a precise manner.
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
86
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
87 .. _`Django`: http://www.djangoproject.com/
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
88 .. _`Genshi`: http://genshi.edgewall.org/
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
89
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
90 Babel accepts a configuration file to specify this mapping of files to
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
91 extraction methods, which is described below.
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
92
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
93
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
94 .. _`frontends`:
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
95
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
96 ----------
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
97 Front-Ends
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
98 ----------
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
99
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
100 Babel provides two different front-ends to access its functionality for working
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
101 with message catalogs:
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
102
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
103 * A `Command-line interface <cmdline.html>`_, and
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
104 * `Integration with distutils/setuptools <setup.html>`_
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
105
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
106 Which one you choose depends on the nature of your project. For most modern
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
107 Python projects, the distutils/setuptools integration is probably more
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
108 convenient.
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
109
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
110
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
111 .. _`mapping`:
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
112
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
113 -------------------------------------------
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
114 Extraction Method Mapping and Configuration
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
115 -------------------------------------------
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
116
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
117 The mapping of extraction methods to files in Babel is done via a configuration
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
118 file. This file maps extended glob patterns to the names of the extraction
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
119 methods, and can also set various options for each pattern (which options are
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
120 available depends on the specific extraction method).
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
121
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
122 For example, the following configuration adds extraction of messages from both
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
123 Genshi markup templates and text templates:
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
124
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
125 .. code-block:: ini
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
126
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
127 # Extraction from Python source files
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
128
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
129 [python: **.py]
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
130
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
131 # Extraction from Genshi HTML and text templates
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
132
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
133 [genshi: **/templates/**.html]
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
134 ignore_tags = script,style
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
135 include_attrs = alt title summary
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
136
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
137 [genshi: **/templates/**.txt]
146
24b5de939850 Some doc fixes.
cmlenz
parents: 126
diff changeset
138 template_class = genshi.template:TextTemplate
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
139 encoding = ISO-8819-15
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
140
554
89292e10bd25 Add JavaScript example.
jruigrok
parents: 270
diff changeset
141 # Extraction from JavaScript files
89292e10bd25 Add JavaScript example.
jruigrok
parents: 270
diff changeset
142
89292e10bd25 Add JavaScript example.
jruigrok
parents: 270
diff changeset
143 [javascript: **.js]
89292e10bd25 Add JavaScript example.
jruigrok
parents: 270
diff changeset
144 extract_messages = $._, jQuery._
89292e10bd25 Add JavaScript example.
jruigrok
parents: 270
diff changeset
145
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
146 The configuration file syntax is based on the format commonly found in ``.INI``
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
147 files on Windows systems, and as supported by the ``ConfigParser`` module in
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
148 the Python standard library. Section names (the strings enclosed in square
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
149 brackets) specify both the name of the extraction method, and the extended glob
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
150 pattern to specify the files that this extraction method should be used for,
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
151 separated by a colon. The options in the sections are passed to the extraction
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
152 method. Which options are available is specific to the extraction method used.
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
153
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
154 The extended glob patterns used in this configuration are similar to the glob
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
155 patterns provided by most shells. A single asterisk (``*``) is a wildcard for
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
156 any number of characters (except for the pathname component separator "/"),
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
157 while a question mark (``?``) only matches a single character. In addition,
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
158 two subsequent asterisk characters (``**``) can be used to make the wildcard
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
159 match any directory level, so the pattern ``**.txt`` matches any file with the
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
160 extension ``.txt`` in any directory.
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
161
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
162 Lines that start with a ``#`` or ``;`` character are ignored and can be used
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
163 for comments. Empty lines are ignored, too.
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
164
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 50
diff changeset
165 .. note:: if you're performing message extraction using the command Babel
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
166 provides for integration into ``setup.py`` scripts, you can also
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
167 provide this configuration in a different way, namely as a keyword
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
168 argument to the ``setup()`` function. See `Distutils/Setuptools
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
169 Integration`_ for more information.
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
170
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
171 .. _`distutils/setuptools integration`: setup.html
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
172
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
173
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
174 Default Extraction Methods
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
175 --------------------------
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
176
555
4ed1a17bff27 Add mention of javascript builtin extractor.
jruigrok
parents: 554
diff changeset
177 Babel comes with a few builtin extractors: ``python`` (which extracts
4ed1a17bff27 Add mention of javascript builtin extractor.
jruigrok
parents: 554
diff changeset
178 messages from Python source files), ``javascript``, and ``ignore`` (which
4ed1a17bff27 Add mention of javascript builtin extractor.
jruigrok
parents: 554
diff changeset
179 extracts nothing).
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
180
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
181 The ``python`` extractor is by default mapped to the glob pattern ``**.py``,
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
182 meaning it'll be applied to all files with the ``.py`` extension in any
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
183 directory. If you specify your own mapping configuration, this default mapping
270
1d25ca7199b0 Fix typo in documentation of the default extraction methods. Thanks to Ramiro Morales for pointing out the mistake.
cmlenz
parents: 252
diff changeset
184 is discarded, so you need to explicitly add it to your mapping (as shown in the
1d25ca7199b0 Fix typo in documentation of the default extraction methods. Thanks to Ramiro Morales for pointing out the mistake.
cmlenz
parents: 252
diff changeset
185 example above.)
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 50
diff changeset
186
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
187
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
188 .. _`referencing extraction methods`:
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
189
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
190 Referencing Extraction Methods
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
191 ------------------------------
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
192
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
193 To be able to use short extraction method names such as “genshi”, you need to
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
194 have `pkg_resources`_ installed, and the package implementing that extraction
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
195 method needs to have been installed with its meta data (the `egg-info`_).
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
196
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
197 If this is not possible for some reason, you need to map the short names to
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
198 fully qualified function names in an extract section in the mapping
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
199 configuration. For example:
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
200
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
201 .. code-block:: ini
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
202
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
203 # Some custom extraction method
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
204
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
205 [extractors]
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
206 custom = mypackage.module:extract_custom
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
207
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
208 [custom: **.ctm]
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
209 some_option = foo
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
210
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
211 Note that the builtin extraction methods ``python`` and ``ignore`` are available
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
212 by default, even if `pkg_resources`_ is not installed. You should never need to
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
213 explicitly define them in the ``[extractors]`` section.
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
214
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
215 .. _`egg-info`: http://peak.telecommunity.com/DevCenter/PythonEggs
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
216 .. _`pkg_resources`: http://peak.telecommunity.com/DevCenter/PkgResources
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 50
diff changeset
217
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
218
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
219 --------------------------
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
220 Writing Extraction Methods
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
221 --------------------------
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
222
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
223 Adding new methods for extracting localizable methods is easy. First, you'll
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
224 need to implement a function that complies with the following interface:
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
225
42
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
226 .. code-block:: python
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
227
86
8a703ecdba91 Some cosmetic changes for the new translator comments support.
cmlenz
parents: 85
diff changeset
228 def extract_xxx(fileobj, keywords, comment_tags, options):
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
229 """Extract messages from XXX files.
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
230
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
231 :param fileobj: the file-like object the messages should be extracted
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
232 from
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
233 :param keywords: a list of keywords (i.e. function names) that should
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
234 be recognized as translation functions
86
8a703ecdba91 Some cosmetic changes for the new translator comments support.
cmlenz
parents: 85
diff changeset
235 :param comment_tags: a list of translator tags to search for and
8a703ecdba91 Some cosmetic changes for the new translator comments support.
cmlenz
parents: 85
diff changeset
236 include in the results
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
237 :param options: a dictionary of additional options (optional)
83
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
238 :return: an iterator over ``(lineno, funcname, message, comments)``
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
239 tuples
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
240 :rtype: ``iterator``
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
241 """
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
242
85
e10f82c1d4c4 Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 83
diff changeset
243 .. note:: Any strings in the tuples produced by this function must be either
e10f82c1d4c4 Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 83
diff changeset
244 ``unicode`` objects, or ``str`` objects using plain ASCII characters.
e10f82c1d4c4 Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 83
diff changeset
245 That means that if sources contain strings using other encodings, it
e10f82c1d4c4 Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 83
diff changeset
246 is the job of the extractor implementation to do the decoding to
e10f82c1d4c4 Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 83
diff changeset
247 ``unicode`` objects.
e10f82c1d4c4 Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 83
diff changeset
248
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
249 Next, you should register that function as an entry point. This requires your
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
250 ``setup.py`` script to use `setuptools`_, and your package to be installed with
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
251 the necessary metadata. If that's taken care of, add something like the
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
252 following to your ``setup.py`` script:
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
253
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
254 .. code-block:: python
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
255
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
256 def setup(...
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
257
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
258 entry_points = """
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
259 [babel.extractors]
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
260 xxx = your.package:extract_xxx
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
261 """,
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
262
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
263 That is, add your extraction method to the entry point group
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
264 ``babel.extractors``, where the name of the entry point is the name that people
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
265 will use to reference the extraction method, and the value being the module and
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
266 the name of the function (separated by a colon) implementing the actual
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
267 extraction.
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
268
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
269 .. note:: As shown in `Referencing Extraction Methods`_, declaring an entry
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
270 point is not strictly required, as users can still reference the
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
271 extraction function directly. But whenever possible, the entry point
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
272 should be declared to make configuration more convenient.
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
273
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
274 .. _`setuptools`: http://peak.telecommunity.com/DevCenter/setuptools
83
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
275
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
276
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
277 -------------------
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
278 Translator Comments
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
279 -------------------
83
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
280
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
281 First of all what are comments tags. Comments tags are excerpts of text to
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
282 search for in comments, only comments, right before the `python gettext`_
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
283 calls, as shown on the following example:
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
284
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
285 .. _`python gettext`: http://docs.python.org/lib/module-gettext.html
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
286
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
287 .. code-block:: python
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
288
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
289 # NOTE: This is a comment about `Foo Bar`
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
290 _('Foo Bar')
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
291
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
292 The comments tag for the above example would be ``NOTE:``, and the translator
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
293 comment for that tag would be ``This is a comment about `Foo Bar```.
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
294
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
295 The resulting output in the catalog template would be something like::
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
296
111
a4389948c992 translator comment tags aren't included in the catalog
pjenvey
parents: 86
diff changeset
297 #. This is a comment about `Foo Bar`
83
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
298 #: main.py:2
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
299 msgid "Foo Bar"
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
300 msgstr ""
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
301
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
302 Now, you might ask, why would I need that?
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
303
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
304 Consider this simple case; you have a menu item called “manual”. You know what
83
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
305 it means, but when the translator sees this they will wonder did you mean:
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
306
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
307 1. a document or help manual, or
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
308 2. a manual process?
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
309
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
310 This is the simplest case where a translation comment such as
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
311 “The installation manual” helps to clarify the situation and makes a translator
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
312 more productive.
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
313
252
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
314 .. note:: Whether translator comments can be extracted depends on the extraction
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
315 method in use. The Python extractor provided by Babel does implement
2398fc97675b Soften dependency on setuptools. Extraction methods can now be referenced using a special section in the mapping configuration, mapping short names to fully-qualified function references.
cmlenz
parents: 146
diff changeset
316 this feature, but others may not.
Copyright (C) 2012-2017 Edgewall Software