Mercurial > babel > old > mirror

annotate doc/catalogs.txt @ 111:a4389948c992

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