Mercurial > genshi > genshi-test

annotate doc/i18n.txt @ 884:5a1c0ee0f659

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improve the template loader docs.
author cmlenz
date Fri, 16 Apr 2010 20:40:28 +0000
parents 0fb43dc2e165
children 80f80f2eec6a
rev   line source
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
2
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
3 =====================================
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
4 Internationalization and Localization
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
5 =====================================
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
6
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
7 Genshi provides basic supporting infrastructure for internationalizing
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
8 and localizing templates. That includes functionality for extracting localizable
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
9 strings from templates, as well as a template filter that can apply translations
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
10 to templates as they get rendered.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
11
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
12 This support is based on `gettext`_ message catalogs and the `gettext Python
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
13 module`_. The extraction process can be used from the API level, or through the
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
14 front-ends implemented by the `Babel`_ project, for which Genshi provides a
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
15 plugin.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
16
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
17 .. _`gettext`: http://www.gnu.org/software/gettext/
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
18 .. _`gettext python module`: http://docs.python.org/lib/module-gettext.html
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
19 .. _`babel`: http://babel.edgewall.org/
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
20
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
21
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
22 .. contents:: Contents
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
23 :depth: 2
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
24 .. sectnum::
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
25
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
26
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
27 Basics
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
28 ======
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
29
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
30 The simplest way to internationalize and translate templates would be to wrap
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
31 all localizable strings in a ``gettext()`` function call (which is often aliased
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
32 to ``_()`` for brevity). In that case, no extra template filter is required.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
33
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
34 .. code-block:: genshi
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
35
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
36 <p>${_("Hello, world!")}</p>
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
37
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
38 However, this approach results in significant “character noise” in templates,
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
39 making them harder to read and preview.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
40
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
41 The ``genshi.filters.Translator`` filter allows you to get rid of the
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
42 explicit `gettext`_ function calls, so you can continue to just write:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
43
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
44 .. code-block:: genshi
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
45
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
46 <p>Hello, world!</p>
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
47
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
48 This text will still be extracted and translated as if you had wrapped it in a
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
49 ``_()`` call.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
50
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
51 .. note:: For parameterized or pluralizable messages, you need to continue using
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
52 the appropriate ``gettext`` functions.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
53
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
54 You can control which tags should be ignored by this process; for example, it
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
55 doesn't really make sense to translate the content of the HTML
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
56 ``<script></script>`` element. Both ``<script>`` and ``<style>`` are excluded
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
57 by default.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
58
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
59 Attribute values can also be automatically translated. The default is to
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
60 consider the attributes ``abbr``, ``alt``, ``label``, ``prompt``, ``standby``,
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
61 ``summary``, and ``title``, which is a list that makes sense for HTML documents.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
62 Of course, you can tell the translator to use a different set of attribute
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
63 names, or none at all.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
64
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
65 In addition, you can control automatic translation in your templates using the
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
66 ``xml:lang`` attribute. If the value of that attribute is a literal string, the
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
67 contents and attributes of the element will be ignored:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
68
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
69 .. code-block:: genshi
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
70
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
71 <p xml:lang="en">Hello, world!</p>
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
72
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
73 On the other hand, if the value of the ``xml:lang`` attribute contains a Python
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
74 expression, the element contents and attributes are still considered for
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
75 automatic translation:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
76
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
77 .. code-block:: genshi
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
78
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
79 <html xml:lang="$locale">
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
80 ...
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
81 </html>
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
82
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
83
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
84 Extraction
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
85 ==========
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
86
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
87 The ``Translator`` class provides a class method called ``extract``, which is
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
88 a generator yielding all localizable strings found in a template or markup
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
89 stream. This includes both literal strings in text nodes and attribute values,
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
90 as well as strings in ``gettext()`` calls in embedded Python code. See the API
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
91 documentation for details on how to use this method directly.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
92
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
93 This functionality is integrated into the message extraction framework provided
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
94 by the `Babel`_ project. Babel provides a command-line interface as well as
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
95 commands that can be used from ``setup.py`` scripts using `Setuptools`_ or
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
96 `Distutils`_.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
97
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
98 .. _`setuptools`: http://peak.telecommunity.com/DevCenter/setuptools
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
99 .. _`distutils`: http://docs.python.org/dist/dist.html
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
100
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
101 The first thing you need to do to make Babel extract messages from Genshi
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
102 templates is to let Babel know which files are Genshi templates. This is done
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
103 using a “mapping configuration”, which can be stored in a configuration file,
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
104 or specified directly in your ``setup.py``.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
105
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
106 In a configuration file, the mapping may look like this:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
107
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
108 .. code-block:: ini
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
109
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
110 # Python souce
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
111 [python:**.py]
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
112
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
113 # Genshi templates
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
114 [genshi:**/templates/**.html]
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
115 include_attrs = title
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
116
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
117 [genshi:**/templates/**.txt]
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
118 template_class = genshi.template.TextTemplate
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
119 encoding = latin-1
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
120
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
121 Please consult the Babel documentation for details on configuration.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
122
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
123 If all goes well, running the extraction with Babel should create a POT file
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
124 containing the strings from your Genshi templates and your Python source files.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
125
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
126 .. note:: Genshi currently does not support “translator comments”, i.e. text in
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
127 template comments that would get added to the POT file. This support
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
128 may or may not be added in future versions.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
129
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
130
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
131 ---------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
132 Configuration Options
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
133 ---------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
134
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
135 The Genshi extraction plugin for Babel supports the following options:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
136
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
137 ``template_class``
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
138 ------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
139 The concrete ``Template`` class that the file should be loaded with. Specify
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
140 the package/module name and the class name, separated by a colon.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
141
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
142 The default is to use ``genshi.template:MarkupTemplate``, and you'll want to
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
143 set it to ``genshi.template:TextTemplate`` for `text templates`_.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
144
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
145 .. _`text templates`: text-templates.html
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
146
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
147 ``encoding``
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
148 ------------
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
149 The encoding of the template file. This is only used for text templates. The
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
150 default is to assume “utf-8”.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
151
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
152 ``include_attrs``
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
153 -----------------
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
154 Comma-separated list of attribute names that should be considered to have
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
155 localizable values. Only used for markup templates.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
156
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
157 ``ignore_tags``
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
158 ---------------
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
159 Comma-separated list of tag names that should be ignored. Only used for markup
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
160 templates.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
161
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
162 ``extract_text``
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
163 ----------------
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
164 Whether text outside explicit ``gettext`` function calls should be extracted.
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
165 By default, any text nodes not inside ignored tags, and values of attribute in
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
166 the ``include_attrs`` list are extracted. If this option is disabled, only
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
167 strings in ``gettext`` function calls are extracted.
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
168
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
169 .. note:: If you disable this option, it's not necessary to add the translation
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
170 filter as described above. You only need to make sure that the
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
171 template has access to the ``gettext`` functions it uses.
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
172
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
173
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
174 Translation
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
175 ===========
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
176
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
177 If you have prepared MO files for use with Genshi using the appropriate tools,
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
178 you can access the message catalogs with the `gettext Python module`_. You'll
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
179 probably want to create a ``gettext.GNUTranslations`` instance, and make the
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
180 translation functions it provides available to your templates by putting them
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
181 in the template context.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
182
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
183 The ``Translator`` filter needs to be added to the filters of the template
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
184 (applying it as a stream filter will likely not have the desired effect).
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
185 Furthermore it needs to be the first filter in the list, including the internal
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
186 filters that Genshi adds itself:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
187
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
188 .. code-block:: python
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
189
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
190 from genshi.filters import Translator
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
191 from genshi.template import MarkupTemplate
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
192
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
193 template = MarkupTemplate("...")
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
194 template.filters.insert(0, Translator(translations.ugettext))
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
195
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
196 If you're using `TemplateLoader`, you should specify a callback function in
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
197 which you add the filter:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
198
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
199 .. code-block:: python
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
200
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
201 from genshi.filters import Translator
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
202 from genshi.template import TemplateLoader
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
203
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
204 def template_loaded(template):
558
2a6cf641cb5e Fix typo in i18n doc.
cmlenz
parents: 528
diff changeset
205 template.filters.insert(0, Translator(translations.ugettext))
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
206
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
207 loader = TemplateLoader('templates', callback=template_loaded)
884
5a1c0ee0f659 Improve the template loader docs.
cmlenz
parents: 594
diff changeset
208 template = loader.load('test.html')
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
209
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
210 This approach ensures that the filter is not added everytime the template is
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
211 loaded, and thus being applied multiple times.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
212
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
213
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
214 Related Considerations
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
215 ======================
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
216
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
217 If you intend to produce an application that is fully prepared for an
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
218 international audience, there are a couple of other things to keep in mind:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
219
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
220 -------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
221 Unicode
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
222 -------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
223
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
224 Use ``unicode`` internally, not encoded bytestrings. Only encode/decode where
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
225 data enters or exits the system. This means that your code works with characters
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
226 and not just with bytes, which is an important distinction for example when
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
227 calculating the length of a piece of text. When you need to decode/encode, it's
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
228 probably a good idea to use UTF-8.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
229
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
230 -------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
231 Date and Time
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
232 -------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
233
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
234 If your application uses datetime information that should be displayed to users
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
235 in different timezones, you should try to work with UTC (universal time)
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
236 internally. Do the conversion from and to "local time" when the data enters or
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
237 exits the system. Make use the Python `datetime`_ module and the third-party
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
238 `pytz`_ package.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
239
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
240 --------------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
241 Formatting and Locale Data
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
242 --------------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
243
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
244 Make sure you check out the functionality provided by the `Babel`_ project for
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
245 things like number and date formatting, locale display strings, etc.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
246
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
247 .. _`datetime`: http://docs.python.org/lib/module-datetime.html
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
248 .. _`pytz`: http://pytz.sourceforge.net/
Copyright (C) 2012-2017 Edgewall Software