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.
This package provides facilities for declaring such messages within program source text; translation of the messages is the responsiblitiy of the 'zope.i18n' package.
Contents
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.
>>> from zope.i18nmessageid import ZopeMessageFactory as _z_
>>> foo = _z_('foo')
>>> foo.domain
'zope'
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)
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.