1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
=============
I18n Messages
=============
Rationale
---------
To translate any text, we must be able to discover the source domain
of the text. A source domain is an identifier that identifies a
project that produces program source strings. Source strings occur as
literals in python programs, text in templates, and some text in XML
data. The project implies a source language and an application
context.
We can think of a source domain as a collection of messages and
associated translation strings.
We often need to create unicode strings that will be displayed by
separate views. The view cannot translate the string without knowing
its source domain. A string or unicode literal carries no domain
information, therefore we use messages. Messages are unicode strings
which carry a translation source domain and possibly a default
translation. They are created by a message factory. The message
factory is created by calling ``MessageFactory`` with the source
domain.
Example
-------
In this example, we create a message factory and assign it to _. By
convention, we use _ as the name of our factory to be compatible with
translatable string extraction tools such as xgettext. We then call _
with a string that needs to be translatable:
>>> from zope.i18nmessageid import MessageFactory, Message
>>> _ = MessageFactory("futurama")
>>> robot = _(u"robot-message", u"${name} is a robot.")
Messages at first seem like they are unicode strings:
>>> robot
u'robot-message'
>>> isinstance(robot, unicode)
True
The additional domain, default and mapping information is available
through attributes:
>>> robot.default
u'${name} is a robot.'
>>> robot.mapping
>>> robot.domain
'futurama'
The message's attributes are considered part of the immutable message
object. They cannot be changed once the message id is created:
>>> robot.domain = "planetexpress"
Traceback (most recent call last):
...
TypeError: readonly attribute
>>> robot.default = u"${name} is not a robot."
Traceback (most recent call last):
...
TypeError: readonly attribute
>>> robot.mapping = {u'name': u'Bender'}
Traceback (most recent call last):
...
TypeError: readonly attribute
If you need to change their information, you'll have to make a new
message id object:
>>> new_robot = Message(robot, mapping={u'name': u'Bender'})
>>> new_robot
u'robot-message'
>>> new_robot.domain
'futurama'
>>> new_robot.default
u'${name} is a robot.'
>>> new_robot.mapping
{u'name': u'Bender'}
Last but not least, messages are reduceable for pickling:
>>> callable, args = new_robot.__reduce__()
>>> callable is Message
True
>>> args
(u'robot-message', 'futurama', u'${name} is a robot.', {u'name': u'Bender'})
>>> fembot = Message(u'fembot')
>>> callable, args = fembot.__reduce__()
>>> callable is Message
True
>>> args
(u'fembot', None, None, None)
Message IDs and backward compatability
--------------------------------------
The change to immutability is not a simple refactoring that can be
coped with backward compatible APIs--it is a change in semantics.
Because immutability is one of those "you either have it or you don't"
things (like pregnancy or death), we will not be able to support both
in one implementation.
The proposed solution for backward compatability is to support both
implementations in parallel, deprecating the mutable one. A separate
factory, ``MessageFactory``, instantiates immutable messages, while
the deprecated old one continues to work like before.
The roadmap to immutable-only message ids is proposed as follows:
Zope 3.1: Immutable message ids are introduced. Security
declarations for mutable message ids are provided to make the
stripping of security proxies unnecessary.
Zope 3.2: Mutable message ids are deprecated.
Zope 3.3: Mutable message ids are removed.
|
