Mercurial > babel > old > babel-test
annotate doc/messages.txt @ 146:9b1336786cb5 stable-0.8.x
Initialized merge tracking via "svnmerge" with revisions "1-140" from
http://svn.edgewall.org/repos/babel/trunk
author | cmlenz |
---|---|
date | Wed, 20 Jun 2007 15:06:17 +0000 |
parents | 641a875e3144 |
children | cd7e378b8190 |
rev | line source |
---|---|
2 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
2 | |
3 ============================= | |
4 Working with Message Catalogs | |
5 ============================= | |
6 | |
7 .. contents:: Contents | |
8 :depth: 2 | |
9 .. sectnum:: | |
10 | |
11 | |
12 Introduction | |
13 ============ | |
14 | |
15 The ``gettext`` translation system enables you to mark any strings used in your | |
16 application as subject to localization, by wrapping them in functions such as | |
17 ``gettext(str)`` and ``ngettext(singular, plural, num)``. For brevity, the | |
40 | 18 ``gettext`` function is often aliased to ``_(str)``, so you can write: |
19 | |
20 .. code-block:: python | |
2 | 21 |
22 print _("Hello") | |
23 | |
40 | 24 instead of just: |
25 | |
26 .. code-block:: python | |
2 | 27 |
28 print "Hello" | |
29 | |
30 to make the string "Hello" localizable. | |
31 | |
32 Message catalogs are collections of translations for such localizable messages | |
33 used in an application. They are commonly stored in PO (Portable Object) and MO | |
34 (Machine Object) files, the formats of which are defined by the GNU `gettext`_ | |
35 tools and the GNU `translation project`_. | |
36 | |
37 .. _`gettext`: http://www.gnu.org/software/gettext/ | |
38 .. _`translation project`: http://sourceforge.net/projects/translation | |
39 | |
40 The general procedure for building message catalogs looks something like this: | |
41 | |
42 * use a tool (such as ``xgettext``) to extract localizable strings from the | |
43 code base and write them to a POT (PO Template) file. | |
44 * make a copy of the POT file for a specific locale (for example, "en_US") | |
45 and start translating the messages | |
46 * use a tool such as ``msgfmt`` to compile the locale PO file into an binary | |
47 MO file | |
48 * later, when code changes make it necessary to update the translations, you | |
49 regenerate the POT file and merge the changes into the various | |
50 locale-specific PO files, for example using ``msgmerge`` | |
51 | |
52 Python provides the `gettext module`_ as part of the standard library, which | |
53 enables applications to work with appropriately generated MO files. | |
54 | |
55 .. _`gettext module`: http://docs.python.org/lib/module-gettext.html | |
56 | |
57 As ``gettext`` provides a solid and well supported foundation for translating | |
58 application messages, Babel does not reinvent the wheel, but rather reuses this | |
59 infrastructure, and makes it easier to build message catalogs for Python | |
60 applications. | |
61 | |
62 | |
63 Message Extraction | |
64 ================== | |
65 | |
66 Babel provides functionality similar to that of the ``xgettext`` program, | |
67 except that only extraction from Python source files is built-in, while support | |
68 for other file formats can be added using a simple extension mechanism. | |
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 | 92 |
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 | 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] |
145 | 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 | 147 |
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 | 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 | 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 | 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 | 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 | 168 Adding new methods for extracting localizable methods is easy. First, you'll |
169 need to implement a function that complies with the following interface: | |
2 | 170 |
40 | 171 .. code-block:: python |
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 | 174 """Extract messages from XXX files. |
175 | |
176 :param fileobj: the file-like object the messages should be extracted | |
177 from | |
178 :param keywords: a list of keywords (i.e. function names) that should | |
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 | 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 | 185 :rtype: ``iterator`` |
186 """ | |
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 | 194 Next, you should register that function as an entry point. This requires your |
195 ``setup.py`` script to use `setuptools`_, and your package to be installed with | |
196 the necessary metadata. If that's taken care of, add something like the | |
197 following to your ``setup.py`` script: | |
198 | |
199 .. code-block:: python | |
200 | |
201 def setup(... | |
202 | |
203 entry_points = """ | |
204 [babel.extractors] | |
205 xxx = your.package:extract_xxx | |
206 """, | |
207 | |
208 That is, add your extraction method to the entry point group | |
209 ``babel.extractors``, where the name of the entry point is the name that people | |
210 will use to reference the extraction method, and the value being the module and | |
211 the name of the function (separated by a colon) implementing the actual | |
212 extraction. | |
213 | |
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 |