Mercurial > babel > old > babel-test

annotate doc/messages.txt @ 556:454fe7a76877 tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update tags
author convert-repo
date Mon, 30 May 2011 21:01:55 +0000
parents 3781cf91ded0
children
rev   line source
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
3 =============================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
4 Working with Message Catalogs
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
5 =============================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7 .. contents:: Contents
250
cd7e378b8190 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 .. sectnum::
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12 Introduction
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
13 ============
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
14
b2492365f186 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
16 application as subject to localization, by wrapping them in functions such as
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
17 ``gettext(str)`` and ``ngettext(singular, plural, num)``. For brevity, the
40
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
18 ``gettext`` function is often aliased to ``_(str)``, so you can write:
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
19
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
20 .. code-block:: python
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
21
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
22 print _("Hello")
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
23
40
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
24 instead of just:
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
25
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
26 .. code-block:: python
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
27
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
28 print "Hello"
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
29
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
30 to make the string "Hello" localizable.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
31
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
32 Message catalogs are collections of translations for such localizable messages
b2492365f186 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
b2492365f186 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`_
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
35 tools and the GNU `translation project`_.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
36
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
37 .. _`gettext`: http://www.gnu.org/software/gettext/
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
38 .. _`translation project`: http://sourceforge.net/projects/translation
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
39
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
40 The general procedure for building message catalogs looks something like this:
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
41
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
42 * use a tool (such as ``xgettext``) to extract localizable strings from the
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
43 code base and write them to a POT (PO Template) file.
b2492365f186 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")
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
45 and start translating the messages
b2492365f186 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
47 MO file
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
48 * later, when code changes make it necessary to update the translations, you
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
49 regenerate the POT file and merge the changes into the various
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
50 locale-specific PO files, for example using ``msgmerge``
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
51
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
52 Python provides the `gettext module`_ as part of the standard library, which
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
53 enables applications to work with appropriately generated MO files.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
54
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
55 .. _`gettext module`: http://docs.python.org/lib/module-gettext.html
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
56
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
57 As ``gettext`` provides a solid and well supported foundation for translating
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
58 application messages, Babel does not reinvent the wheel, but rather reuses this
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
59 infrastructure, and makes it easier to build message catalogs for Python
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
60 applications.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
61
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
62
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
63 Message Extraction
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
64 ==================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
65
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
66 Babel provides functionality similar to that of the ``xgettext`` program,
b2492365f186 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
68 for other file formats can be added using a simple extension mechanism.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
69
48
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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``,
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
76
bd647e3760e0 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,
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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,
bd647e3760e0 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`_
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
86
bd647e3760e0 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/
bd647e3760e0 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/
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
89
bd647e3760e0 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
bd647e3760e0 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
92
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
93
250
cd7e378b8190 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`:
cd7e378b8190 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
cd7e378b8190 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 ----------
cd7e378b8190 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
cd7e378b8190 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 ----------
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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:
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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>`_
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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.
cd7e378b8190 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
cd7e378b8190 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
111 .. _`mapping`:
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
112
48
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
113 -------------------------------------------
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
115 -------------------------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
116
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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).
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
121
bd647e3760e0 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
bd647e3760e0 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:
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
124
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
125 .. code-block:: ini
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
126
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
128
250
cd7e378b8190 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
130
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
132
250
cd7e378b8190 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
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
136
250
cd7e378b8190 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
a5914ba672d1 Some doc fixes.
cmlenz
parents: 124
diff changeset
138 template_class = genshi.template:TextTemplate
48
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
140
552
d96425d9dceb Add JavaScript example.
jruigrok
parents: 268
diff changeset
141 # Extraction from JavaScript files
d96425d9dceb Add JavaScript example.
jruigrok
parents: 268
diff changeset
142
d96425d9dceb Add JavaScript example.
jruigrok
parents: 268
diff changeset
143 [javascript: **.js]
d96425d9dceb Add JavaScript example.
jruigrok
parents: 268
diff changeset
144 extract_messages = $._, jQuery._
d96425d9dceb Add JavaScript example.
jruigrok
parents: 268
diff changeset
145
48
bd647e3760e0 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``
bd647e3760e0 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
cd7e378b8190 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
bd647e3760e0 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
bd647e3760e0 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,
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
153
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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 "/"),
bd647e3760e0 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,
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
161
bd647e3760e0 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
cd7e378b8190 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
164
49
daf35e2ad044 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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.
cd7e378b8190 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
cd7e378b8190 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
172
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
173
250
cd7e378b8190 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
cd7e378b8190 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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
176
553
3781cf91ded0 Add mention of javascript builtin extractor.
jruigrok
parents: 552
diff changeset
177 Babel comes with a few builtin extractors: ``python`` (which extracts
3781cf91ded0 Add mention of javascript builtin extractor.
jruigrok
parents: 552
diff changeset
178 messages from Python source files), ``javascript``, and ``ignore`` (which
3781cf91ded0 Add mention of javascript builtin extractor.
jruigrok
parents: 552
diff changeset
179 extracts nothing).
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
180
250
cd7e378b8190 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``,
cd7e378b8190 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
cd7e378b8190 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
4fb303dfd27a 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
4fb303dfd27a 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
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
186
250
cd7e378b8190 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
cd7e378b8190 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`:
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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 ------------------------------
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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`_).
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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:
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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]
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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]
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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.
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
217
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
218
48
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
219 --------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
220 Writing Extraction Methods
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
221 --------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
222
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
223 Adding new methods for extracting localizable methods is easy. First, you'll
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
224 need to implement a function that complies with the following interface:
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
225
40
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
226 .. code-block:: python
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
227
84
4ff9cc26c11b Some cosmetic changes for the new translator comments support.
cmlenz
parents: 83
diff changeset
228 def extract_xxx(fileobj, keywords, comment_tags, options):
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
229 """Extract messages from XXX files.
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
230
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
231 :param fileobj: the file-like object the messages should be extracted
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
232 from
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
233 :param keywords: a list of keywords (i.e. function names) that should
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
234 be recognized as translation functions
84
4ff9cc26c11b 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
4ff9cc26c11b Some cosmetic changes for the new translator comments support.
cmlenz
parents: 83
diff changeset
236 include in the results
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
237 :param options: a dictionary of additional options (optional)
81
1e89661e6b26 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)``
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
239 tuples
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
240 :rtype: ``iterator``
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
241 """
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
242
83
6b6aa2f9e93d 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
6b6aa2f9e93d 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.
6b6aa2f9e93d 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
6b6aa2f9e93d 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
6b6aa2f9e93d Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 81
diff changeset
247 ``unicode`` objects.
6b6aa2f9e93d Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 81
diff changeset
248
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
249 Next, you should register that function as an entry point. This requires your
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
250 ``setup.py`` script to use `setuptools`_, and your package to be installed with
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
251 the necessary metadata. If that's taken care of, add something like the
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
252 following to your ``setup.py`` script:
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
253
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
254 .. code-block:: python
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
255
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
256 def setup(...
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
257
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
258 entry_points = """
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
259 [babel.extractors]
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
260 xxx = your.package:extract_xxx
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
261 """,
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
262
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
263 That is, add your extraction method to the entry point group
dd5c3ba59eae 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
dd5c3ba59eae 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
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
266 the name of the function (separated by a colon) implementing the actual
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
267 extraction.
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
268
250
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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.
cd7e378b8190 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
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
274 .. _`setuptools`: http://peak.telecommunity.com/DevCenter/setuptools
81
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
275
250
cd7e378b8190 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
cd7e378b8190 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 -------------------
cd7e378b8190 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
cd7e378b8190 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
280
1e89661e6b26 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
1e89661e6b26 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`_
1e89661e6b26 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:
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
284
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
286
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
287 .. code-block:: python
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
288
1e89661e6b26 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`
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
290 _('Foo Bar')
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
291
1e89661e6b26 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
1e89661e6b26 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```.
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
294
1e89661e6b26 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::
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
296
109
ce331dac98fe translator comment tags aren't included in the catalog
pjenvey
parents: 84
diff changeset
297 #. This is a comment about `Foo Bar`
81
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
298 #: main.py:2
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
299 msgid "Foo Bar"
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
300 msgstr ""
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
301
1e89661e6b26 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?
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
303
250
cd7e378b8190 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
1e89661e6b26 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:
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
306
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
308 2. a manual process?
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
309
1e89661e6b26 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
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
312 more productive.
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
313
250
cd7e378b8190 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
cd7e378b8190 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
cd7e378b8190 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