Mercurial > babel > mirror

annotate doc/messages.txt @ 591:d1618dfaf114 trunk

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