Mercurial > genshi > genshi-test

annotate doc/i18n.txt @ 928:bd390c56ecef stable-0.6.x

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge r1150 from trunk (fix i18n namespace documentaton issue #400).
author hodgestar
date Thu, 10 Mar 2011 08:50:44 +0000
parents 158aafe7187f
children
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
886
9bd255289d75 Set reST MIME type on new loader doc page.
cmlenz
parents: 885
diff changeset
7 Genshi provides comprehensive supporting infrastructure for internationalizing
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
8 and localizing templates. That includes functionality for extracting
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
9 localizable strings from templates, as well as a template filter and special
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
10 directives that can apply translations to templates as they get rendered.
528
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
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
13 module`_. The extraction process can be used from the API level, or through
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
14 the front-ends implemented by the `Babel`_ project, for which Genshi provides
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
15 a plugin.
528
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
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
31 all localizable strings in a ``gettext()`` function call (which is often
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
32 aliased to ``_()`` for brevity). In that case, no extra template filter is
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
33 required.
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
34
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
35 .. code-block:: genshi
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
36
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
37 <p>${_("Hello, world!")}</p>
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
38
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
39 However, this approach results in significant “character noise” in templates,
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
40 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
41
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
42 The ``genshi.filters.Translator`` filter allows you to get rid of the
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
43 explicit `gettext`_ function calls, so you can (often) just continue to write:
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
44
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
45 .. code-block:: genshi
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
46
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
47 <p>Hello, world!</p>
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
48
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
49 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
50 ``_()`` call.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
51
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
52 .. note:: For parameterized or pluralizable messages, you need to use the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
53 special `template directives`_ described below, or use the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
54 corresponding ``gettext`` function in embedded Python expressions.
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
55
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
56 You can control which tags should be ignored by this process; for example, it
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
57 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
58 ``<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
59 by default.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
60
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
61 Attribute values can also be automatically translated. The default is to
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
62 consider the attributes ``abbr``, ``alt``, ``label``, ``prompt``, ``standby``,
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
63 ``summary``, and ``title``, which is a list that makes sense for HTML
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
64 documents. Of course, you can tell the translator to use a different set of
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
65 attribute names, or none at all.
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
66
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
67 ----------------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
68 Language Tagging
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
69 ----------------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
70
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
71 You can control automatic translation in your templates using the ``xml:lang``
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
72 attribute. If the value of that attribute is a literal string, the contents and
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
73 attributes of the element will be ignored:
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
74
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
75 .. code-block:: genshi
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 <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
78
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
79 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
80 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
81 automatic translation:
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 .. code-block:: genshi
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
84
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
85 <html xml:lang="$locale">
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 </html>
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
88
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
89
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
90 .. _`template directives`:
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
91
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
92 Template Directives
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
93 ===================
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
94
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
95 Sometimes localizable strings in templates may contain dynamic parameters, or
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
96 they may depend on the numeric value of some variable to choose a proper
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
97 plural form. Sometimes the strings contain embedded markup, such as tags for
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
98 emphasis or hyperlinks, and you don't want to rely on the people doing the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
99 translations to know the syntax and escaping rules of HTML and XML.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
100
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
101 In those cases the simple text extraction and translation process described
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
102 above is not sufficient. You could just use ``gettext`` API functions in
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
103 embedded Python expressions for parameters and pluralization, but that does
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
104 not help when messages contain embedded markup. Genshi provides special
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
105 template directives for internationalization that attempt to provide a
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
106 comprehensive solution for this problem space.
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
107
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
108 To enable these directives, you'll need to register them with the templates
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
109 they are used in. You can do this by adding them manually via the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
110 ``Template.add_directives(namespace, factory)`` (where ``namespace`` would be
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
111 “http://genshi.edgewall.org/i18n” and ``factory`` would be an instance of the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
112 ``Translator`` class). Or you can just call the ``Translator.setup(template)``
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
113 class method, which both registers the directives and adds the translation
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
114 filter.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
115
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
116 After the directives have been registered with the template engine on the
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
117 Python side of your application, you need to declare the corresponding
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
118 directive namespace in all markup templates that use them. For example:
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
119
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
120 .. code-block:: genshi
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
121
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
122 <html xmlns:py="http://genshi.edgewall.org/"
928
bd390c56ecef Merge r1150 from trunk (fix i18n namespace documentaton issue #400).
hodgestar
parents: 890
diff changeset
123 xmlns:i18n="http://genshi.edgewall.org/i18n">
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
124 …
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
125 </html>
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
126
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
127 These directives only make sense in the context of `markup templates`_. For
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
128 `text templates`_, you can just use the corresponding ``gettext`` API calls as needed.
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
129
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
130 .. note:: The internationalization directives are still somewhat experimental
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
131 and have some known issues. However, the attribute language they
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
132 implement should be stable and is not subject to change
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
133 substantially in future versions.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
134
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
135 .. _`markup templates`: xml-templates.html
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
136 .. _`text templates`: text-templates.html
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
137
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
138 --------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
139 Messages
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
140 --------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
141
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
142 ``i18n:msg``
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
143 ------------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
144
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
145 This is the basic directive for defining localizable text passages that
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
146 contain parameters and/or markup.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
147
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
148 For example, consider the following template snippet:
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
149
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
150 .. code-block:: genshi
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
151
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
152 <p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
153 Please visit <a href="${site.url}">${site.name}</a> for help.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
154 </p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
155
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
156 Without further annotation, the translation filter would treat this sentence
887
148c17f49111 More doc improvements.
cmlenz
parents: 886
diff changeset
157 as two separate messages (“Please visit” and “for help”), and the translator
148c17f49111 More doc improvements.
cmlenz
parents: 886
diff changeset
158 would have no control over the position of the link in the sentence.
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
159
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
160 However, when you use the Genshi internationalization directives, you simply
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
161 add an ``i18n:msg`` attribute to the enclosing ``<p>`` element:
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
162
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
163 .. code-block:: genshi
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
164
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
165 <p i18n:msg="name">
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
166 Please visit <a href="${site.url}">${site.name}</a> for help.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
167 </p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
168
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
169 Genshi is then able to identify the text in the ``<p>`` element as a single
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
170 message for translation purposes. You'll see the following string in your
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
171 message catalog::
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
172
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
173 Please visit [1:%(name)s] for help.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
174
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
175 The `<a>` element with its attribute has been replaced by a part in square
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
176 brackets, which does not include the tag name or the attributes of the element.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
177
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
178 The value of the ``i18n:msg`` attribute is a comma-separated list of parameter
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
179 names, which serve as simplified aliases for the actual Python expressions the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
180 message contains. The order of the paramer names in the list must correspond
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
181 to the order of the expressions in the text. In this example, there is only
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
182 one parameter: its alias for translation is “name”, while the corresponding
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
183 expression is ``${site.name}``.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
184
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
185 The translator now has complete control over the structure of the sentence. He
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
186 or she certainly does need to make sure that any bracketed parts are not
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
187 removed, and that the ``name`` parameter is preserved correctly. But those are
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
188 things that can be easily checked by validating the message catalogs. The
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
189 important thing is that the translator can change the sentence structure, and
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
190 has no way to break the application by forgetting to close a tag, for example.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
191
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
192 So if the German translator of this snippet decided to translate it to::
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
193
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
194 Um Hilfe zu erhalten, besuchen Sie bitte [1:%(name)s]
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
195
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
196 The resulting output might be:
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
197
889
e9827ccf94ee Minor fix for i18n doc.
cmlenz
parents: 888
diff changeset
198 .. code-block:: xml
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
199
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
200 <p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
201 Um Hilfe zu erhalten, besuchen Sie bitte
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
202 <a href="http://example.com/">Example</a>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
203 </p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
204
887
148c17f49111 More doc improvements.
cmlenz
parents: 886
diff changeset
205 Messages may contain multiple tags, and they may also be nested. For example:
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
206
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
207 .. code-block:: genshi
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
208
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
209 <p i18n:msg="name">
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
210 <i>Please</i> visit <b>the site <a href="${site.url}">${site.name}</a></b>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
211 for help.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
212 </p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
213
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
214 This would result in the following message ID::
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
215
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
216 [1:Please] visit [2:the site [3:%(name)s]] for help.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
217
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
218 Again, the translator has full control over the structure of the sentence. So
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
219 the German translation could actually look like this::
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
220
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
221 Um Hilfe zu erhalten besuchen Sie [1:bitte]
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
222 [3:%(name)s], [2:das ist eine Web-Site]
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
223
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
224 Which Genshi would recompose into the following outout:
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
225
889
e9827ccf94ee Minor fix for i18n doc.
cmlenz
parents: 888
diff changeset
226 .. code-block:: xml
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
227
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
228 <p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
229 Um Hilfe zu erhalten besuchen Sie <i>bitte</i>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
230 <a href="http://example.com/">Example</a>, <b>das ist eine Web-Site</b>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
231 </p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
232
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
233 Note how the translation has changed the order and even the nesting of the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
234 tags.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
235
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
236 .. warning:: Please note that ``i18n:msg`` directives do not support other
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
237 nested directives. Directives commonly change the structure of
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
238 the generated markup dynamically, which often would result in the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
239 structure of the text changing, thus making translation as a
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
240 single message ineffective.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
241
888
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
242 ``i18n:choose``, ``i18n:singular``, ``i18n:plural``
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
243 ---------------------------------------------------
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
244
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
245 Translatable strings that vary based on some number of objects, such as “You
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
246 have 1 new message” or “You have 3 new messages”, present their own challenge,
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
247 in particular when you consider that different languages have different rules
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
248 for pluralization. For example, while English and most western languages have
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
249 two plural forms (one for ``n=1`` and an other for ``n<>1``), Welsh has five
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
250 different plural forms, while Hungarian only has one.
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
251
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
252 The ``gettext`` framework has long supported this via the ``ngettext()``
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
253 family of functions. You specify two default messages, one singular and one
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
254 plural, and the number of items. The translations however may contain any
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
255 number of plural forms for the message, depending on how many are commonly
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
256 used in the language. ``ngettext`` will choose the correct plural form of the
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
257 translated message based on the specified number of items.
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
258
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
259 Genshi provides a variant of the ``i18n:msg`` directive described above that
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
260 allows choosing the proper plural form based on the numeric value of a given
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
261 variable. The pluralization support is implemented in a set of three
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
262 directives that must be used together: ``i18n:choose``, ``i18n:singular``, and
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
263 ``i18n:plural``.
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
264
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
265 The ``i18n:choose`` directive is used to set up the context of the message: it
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
266 simply wraps the singular and plural variants.
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
267
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
268 The value of this directive is split into two parts: the first is the
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
269 *numeral*, a Python expression that evaluates to a number to determine which
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
270 plural form should be chosen. The second part, separated by a semicolon, lists
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
271 the parameter names. This part is equivalent to the value of the ``i18n:msg``
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
272 directive.
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
273
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
274 For example:
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
275
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
276 .. code-block:: genshi
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
277
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
278 <p i18n:choose="len(messages); num">
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
279 <i18n:singular>You have <b>${len(messages)}</b> new message.</i18n:singular>
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
280 <i18n:plural>You have <b>${len(messages)}</b> new messages.</i18n:plural>
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
281 </p>
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
282
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
283 All three directives can be used either as elements or attribute. So the above
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
284 example could also be written as follows:
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
285
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
286 .. code-block:: genshi
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
287
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
288 <i18n:choose numeral="len(messages)" params="num">
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
289 <p i18n:singular="">You have <b>${len(messages)}</b> new message.</p>
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
290 <p i18n:plural="">You have <b>${len(messages)}</b> new messages.</p>
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
291 </i18n:choose>
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
292
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
293 When used as an element, the two parts of the ``i18n:choose`` value are split
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
294 into two different attributes: ``numeral`` and ``params``. The
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
295 ``i18n:singular`` and ``i18n:plural`` directives do not require or support any
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
296 value (or any extra attributes).
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
297
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
298 --------------------
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
299 Comments and Domains
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
300 --------------------
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
301
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
302 ``i18n:comment``
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
303 ----------------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
304
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
305 The ``i18n:comment`` directive can be used to supply a comment for the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
306 translator. For example, if a template snippet is not easily understood
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
307 outside of its context, you can add a translator comment to help the
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
308 translator understand in what context the message will be used:
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
309
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
310 .. code-block:: genshi
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
311
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
312 <p i18n:msg="name" i18n:comment="Link to the relevant support site">
887
148c17f49111 More doc improvements.
cmlenz
parents: 886
diff changeset
313 Please visit <a href="${site.url}">${site.name}</a> for help.
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
314 </p>
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
315
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
316 This comment will be extracted together with the message itself, and will
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
317 commonly be placed along the message in the message catalog, so that it is
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
318 easily visible to the person doing the translation.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
319
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
320 This directive has no impact on how the template is rendered, and is ignored
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
321 outside of the extraction process.
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
322
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
323 ``i18n:domain``
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
324 ---------------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
325
888
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
326 In larger projects, message catalogs are commonly split up into different
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
327 *domains*. For example, you might have a core application domain, and then
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
328 separate domains for extensions or libraries.
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
329
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
330 Genshi provides a directive called ``i18n:domain`` that lets you choose the
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
331 translation domain for a particular scope. For example:
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
332
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
333 .. code-block:: genshi
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
334
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
335 <div i18n:domain="examples">
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
336 <p>Hello, world!</p>
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
337 </div>
18dee397f8e1 More i18n doc improvements.
cmlenz
parents: 887
diff changeset
338
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
339
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
340 Extraction
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
341 ==========
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
342
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
343 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
344 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
345 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
346 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
347 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
348
885
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
349 -----------------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
350 Babel Integration
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
351 -----------------
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
352
80f80f2eec6a Started extending the i18n docs.
cmlenz
parents: 884
diff changeset
353 This functionality is integrated with the message extraction framework provided
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
354 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
355 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
356 `Distutils`_.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
357
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
358 .. _`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
359 .. _`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
360
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
361 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
362 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
363 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
364 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
365
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
366 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
367
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
368 .. code-block:: ini
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
369
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
370 # Python souce
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
371 [python:**.py]
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
372
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
373 # Genshi templates
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
374 [genshi:**/templates/**.html]
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
375 include_attrs = title
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
376
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
377 [genshi:**/templates/**.txt]
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
378 template_class = genshi.template.TextTemplate
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
379 encoding = latin-1
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
380
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
381 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
382
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
383 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
384 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
385
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
386
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
387 ---------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
388 Configuration Options
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
389 ---------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
390
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
391 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
392
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
393 ``template_class``
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
394 ------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
395 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
396 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
397
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
398 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
399 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
400
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
401 .. _`text templates`: text-templates.html
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
402
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
403 ``encoding``
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
404 ------------
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
405 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
406 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
407
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
408 ``include_attrs``
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
409 -----------------
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
410 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
411 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
412
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
413 ``ignore_tags``
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
414 ---------------
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
415 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
416 templates.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
417
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
418 ``extract_text``
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
419 ----------------
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
420 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
421 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
422 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
423 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
424
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
425 .. note:: If you disable this option, and do not make use of the
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
426 internationalization directives, it's not necessary to add the
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
427 translation filter as described above. You only need to make sure
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
428 that the template has access to the ``gettext`` functions it uses.
594
0fb43dc2e165 Add option to I18n filter to only extract strings in gettext function calls.
cmlenz
parents: 558
diff changeset
429
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
430
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
431 Translation
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
432 ===========
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
433
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
434 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
435 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
436 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
437 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
438 in the template context.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
439
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
440 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
441 (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
442 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
443 filters that Genshi adds itself:
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
444
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
445 .. code-block:: python
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
446
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
447 from genshi.filters import Translator
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
448 from genshi.template import MarkupTemplate
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
449
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
450 template = MarkupTemplate("...")
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
451 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
452
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
453 The ``Translator`` class also provides the convenience method ``setup()``,
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
454 which will both add the filter and register the i18n directives:
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
455
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
456 .. code-block:: python
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
457
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
458 from genshi.filters import Translator
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
459 from genshi.template import MarkupTemplate
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
460
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
461 template = MarkupTemplate("...")
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
462 translator = Translator(translations.ugettext)
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
463 translator.setup(template)
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
464
890
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
465 .. warning:: If you're using ``TemplateLoader``, you should specify a
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
466 `callback function`_ in which you add the filter. That ensures
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
467 that the filter is not added everytime the template is rendered,
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
468 thereby being applied multiple times.
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
469
158aafe7187f More doc tweaks.
cmlenz
parents: 889
diff changeset
470 .. _`callback function`: loader.html#callback-interface
528
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
471
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
472
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
473 Related Considerations
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
474 ======================
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
475
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
476 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
477 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
478
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
479 -------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
480 Unicode
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
481 -------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
482
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
483 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
484 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
485 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
486 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
487 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
488
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
489 -------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
490 Date and Time
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
491 -------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
492
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
493 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
494 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
495 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
496 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
497 `pytz`_ package.
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
498
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
499 --------------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
500 Formatting and Locale Data
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
501 --------------------------
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
502
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
503 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
504 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
505
f38ce008ab0a Integrated [http://babel.edgewall.org/ Babel] message extraction plugin, and added I18n doc page.
cmlenz
parents:
diff changeset
506 .. _`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
507 .. _`pytz`: http://pytz.sourceforge.net/
Copyright (C) 2012-2017 Edgewall Software