Mercurial > babel > old > babel-test

annotate doc/messages.txt @ 532:256ba67f06d0

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