Mercurial > babel > old > babel-test

annotate doc/messages.txt @ 154:4d2117dfd7f5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
The default ordering of messages in generated POT files, which is based on the order those messages are found when walking the source tree, is no longer subject to differences between platforms; directory and file names are now always sorted alphabetically.
author cmlenz
date Wed, 20 Jun 2007 21:41:00 +0000
parents a5914ba672d1
children cd7e378b8190
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
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 :depth: 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
48
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
94 .. _`mapping`:
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
95
48
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
96 -------------------------------------------
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
98 -------------------------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
99
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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).
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
104
bd647e3760e0 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
bd647e3760e0 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:
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
107
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
108 .. code-block:: ini
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
109
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
111
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
112 [python: foobar/**.py]
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 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
115
bd647e3760e0 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]
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
119
bd647e3760e0 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
a5914ba672d1 Some doc fixes.
cmlenz
parents: 124
diff changeset
121 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
122 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
123
bd647e3760e0 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``
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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,
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
131
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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 "/"),
bd647e3760e0 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,
bd647e3760e0 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
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
139
bd647e3760e0 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
bd647e3760e0 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.
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
142
49
daf35e2ad044 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
daf35e2ad044 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
daf35e2ad044 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
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
146 keyword argument to the ``setup()`` function.
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
147
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
148
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
149 ----------
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
150 Front-Ends
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
151 ----------
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
152
49
daf35e2ad044 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
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
154 with message catalogs:
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
155
49
daf35e2ad044 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
3ed77bf655d1 Typo on `doc/catalogs.txt`.
palgarvio
parents: 73
diff changeset
157 * `Integration with distutils/setuptools <setup.html>`_
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
158
daf35e2ad044 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
daf35e2ad044 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
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
161 convenient.
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 48
diff changeset
162
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
163
48
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
164 --------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
165 Writing Extraction Methods
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
166 --------------------------
bd647e3760e0 Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
cmlenz
parents: 40
diff changeset
167
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
168 Adding new methods for extracting localizable methods is easy. First, you'll
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
169 need to implement a function that complies with the following interface:
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
170
40
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
171 .. code-block:: python
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
172
84
4ff9cc26c11b Some cosmetic changes for the new translator comments support.
cmlenz
parents: 83
diff changeset
173 def extract_xxx(fileobj, keywords, comment_tags, options):
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
174 """Extract messages from XXX files.
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
175
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
176 :param fileobj: the file-like object the messages should be extracted
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
177 from
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
178 :param keywords: a list of keywords (i.e. function names) that should
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
179 be recognized as translation functions
84
4ff9cc26c11b 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
4ff9cc26c11b Some cosmetic changes for the new translator comments support.
cmlenz
parents: 83
diff changeset
181 include in the results
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
182 :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
183 :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
184 tuples
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
185 :rtype: ``iterator``
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
186 """
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
187
83
6b6aa2f9e93d 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
6b6aa2f9e93d 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.
6b6aa2f9e93d 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
6b6aa2f9e93d 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
6b6aa2f9e93d Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 81
diff changeset
192 ``unicode`` objects.
6b6aa2f9e93d Add unit tests for extracting translator comments from python sources.
cmlenz
parents: 81
diff changeset
193
73
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
194 Next, you should register that function as an entry point. This requires your
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
195 ``setup.py`` script to use `setuptools`_, and your package to be installed with
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
196 the necessary metadata. If that's taken care of, add something like the
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
197 following to your ``setup.py`` script:
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
198
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
199 .. code-block:: python
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
200
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
201 def setup(...
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
202
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
203 entry_points = """
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
204 [babel.extractors]
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
205 xxx = your.package:extract_xxx
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
206 """,
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
207
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
208 That is, add your extraction method to the entry point group
dd5c3ba59eae 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
dd5c3ba59eae 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
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
211 the name of the function (separated by a colon) implementing the actual
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
212 extraction.
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
213
dd5c3ba59eae Extended the docs a bit.
cmlenz
parents: 49
diff changeset
214 .. _`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
215
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
216 Comments Tags And Translator Comments Explanation
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
217 .................................................
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
218
1e89661e6b26 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
1e89661e6b26 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`_
1e89661e6b26 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:
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
222
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
224
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
225 .. code-block:: python
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
226
1e89661e6b26 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`
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
228 _('Foo Bar')
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
229
1e89661e6b26 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
1e89661e6b26 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```.
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
232
1e89661e6b26 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::
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
234
109
ce331dac98fe translator comment tags aren't included in the catalog
pjenvey
parents: 84
diff changeset
235 #. 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
236 #: main.py:2
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
237 msgid "Foo Bar"
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
238 msgstr ""
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
239
1e89661e6b26 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?
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
241
1e89661e6b26 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
1e89661e6b26 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:
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
244
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
246 2. a manual process?
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
247
1e89661e6b26 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
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
250 more productive.
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
251
1e89661e6b26 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**
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
253
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
255 “Forward” in Northern Sotho:
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
256
1e89661e6b26 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,
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
259 talking about.
1e89661e6b26 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’
1e89661e6b26 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”
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
262 and “show next page in history”.
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
263
1e89661e6b26 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
1e89661e6b26 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.
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
266
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
267 .. _`sleuths`: http://www.thefreedictionary.com/sleuth
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
268
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
269
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
270 *Explanation Borrowed From:* `Wordforge`_
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
271
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
273
1e89661e6b26 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
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
275 code.
1e89661e6b26 Fixed and added some documentation about the translator comments implemented in [81].
palgarvio
parents: 76
diff changeset
276
Copyright (C) 2012-2017 Edgewall Software