Mercurial > babel > mirror

annotate doc/messages.txt @ 210:9c237f83d7cb trunk

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