Mercurial > babel > old > mirror

annotate doc/messages.txt @ 506:e57f6c0e371b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Back out r549 for now.
author jruigrok
date Tue, 22 Feb 2011 16:01:21 +0000
parents 1d25ca7199b0
children 89292e10bd25
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
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
141 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
142 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
143 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
144 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
145 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
146 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
147 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
148
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
149 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
150 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
151 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
152 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
153 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
154 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
155 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
156
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
157 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
158 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
159
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 50
diff changeset
160 .. 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
161 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
162 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
163 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
164 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
165
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 .. _`distutils/setuptools integration`: setup.html
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
167
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
168
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
169 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
170 --------------------------
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
171
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
172 Babel comes with only two builtin extractors: ``python`` (which extracts
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
173 messages from Python source files) and ``ignore`` (which extracts nothing).
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
174
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
175 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
176 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
177 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
178 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
179 example above.)
51
3664c93860f1 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 50
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
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 .. _`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
183
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
184 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
185 ------------------------------
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
186
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 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
188 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
189 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
190
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 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
192 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
193 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
194
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 .. 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
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 # 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
198
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 [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
200 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
201
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 [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
203 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
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 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
206 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
207 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
208
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 .. _`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
210 .. _`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
211
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
212
50
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
213 --------------------------
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
214 Writing Extraction Methods
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
215 --------------------------
b6497cfd06d6 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 42
diff changeset
216
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
217 Adding new methods for extracting localizable methods is easy. First, you'll
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
218 need to implement a function that complies with the following interface:
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
219
42
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
220 .. code-block:: python
cf94e70a77f3 Syntax highlighting for the docs.
cmlenz
parents: 4
diff changeset
221
86
8a703ecdba91 Some cosmetic changes for the new translator comments support.
cmlenz
parents: 85
diff changeset
222 def extract_xxx(fileobj, keywords, comment_tags, options):
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
223 """Extract messages from XXX files.
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
224
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
225 :param fileobj: the file-like object the messages should be extracted
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
226 from
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
227 :param keywords: a list of keywords (i.e. function names) that should
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
228 be recognized as translation functions
86
8a703ecdba91 Some cosmetic changes for the new translator comments support.
cmlenz
parents: 85
diff changeset
229 :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
230 include in the results
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
231 :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
232 :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
233 tuples
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
234 :rtype: ``iterator``
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
235 """
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
236
85
e10f82c1d4c4 Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 83
diff changeset
237 .. 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
238 ``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
239 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
240 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
241 ``unicode`` objects.
e10f82c1d4c4 Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 83
diff changeset
242
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
243 Next, you should register that function as an entry point. This requires your
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
244 ``setup.py`` script to use `setuptools`_, and your package to be installed with
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
245 the necessary metadata. If that's taken care of, add something like the
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
246 following to your ``setup.py`` script:
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
247
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
248 .. code-block:: python
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
249
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
250 def setup(...
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
251
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
252 entry_points = """
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
253 [babel.extractors]
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
254 xxx = your.package:extract_xxx
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
255 """,
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
256
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
257 That is, add your extraction method to the entry point group
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
258 ``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
259 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
260 the name of the function (separated by a colon) implementing the actual
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
261 extraction.
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
262
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
263 .. 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
264 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
265 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
266 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
267
75
98b27ffe1c3a Extended the docs a bit.
cmlenz
parents: 51
diff changeset
268 .. _`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
269
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
270
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 -------------------
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 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
273 -------------------
83
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
274
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
275 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
276 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
277 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
278
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
279 .. _`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
280
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
281 .. code-block:: python
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
282
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
283 # 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
284 _('Foo Bar')
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
285
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
286 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
287 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
288
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
289 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
290
111
a4389948c992 translator comment tags aren't included in the catalog
pjenvey
parents: 86
diff changeset
291 #. 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
292 #: main.py:2
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
293 msgid "Foo Bar"
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
294 msgstr ""
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
295
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
296 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
297
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
298 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
299 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
300
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
301 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
302 2. a manual process?
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
303
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
304 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
305 “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
306 more productive.
80e895a498a3 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 78
diff changeset
307
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
308 .. 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
309 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
310 this feature, but others may not.
Copyright (C) 2012-2017 Edgewall Software