import re
from gettext import NullTranslations
from translationstring.compat import text_type
from translationstring.compat import string_types
from translationstring.compat import PY3
NAME_RE = r"[a-zA-Z][-a-zA-Z0-9_]*"
_interp_regex = re.compile(r'(?<!\$)(\$(?:(%(n)s)|{(%(n)s)}))'
% ({'n': NAME_RE}))
CONTEXT_MASK = text_type('%s\x04%s')
[docs]
class TranslationString(text_type):
"""
The constructor for a :term:`translation string`. A translation
string is a Unicode-like object that has some extra metadata.
This constructor accepts one required argument named ``msgid``.
``msgid`` must be the :term:`message identifier` for the
translation string. It must be a ``unicode`` object or a ``str``
object encoded in the default system encoding.
Optional keyword arguments to this object's constructor include
``domain``, ``default``, and ``mapping``.
``domain`` represents the :term:`translation domain`. By default,
the translation domain is ``None``, indicating that this
translation string is associated with the default translation
domain (usually ``messages``).
``default`` represents an explicit *default text* for this
translation string. Default text appears when the translation
string cannot be translated. Usually, the ``msgid`` of a
translation string serves double duty as its default text.
However, using this option you can provide a different default
text for this translation string. This feature is useful when the
default of a translation string is too complicated or too long to
be used as a message identifier. If ``default`` is provided, it
must be a ``unicode`` object or a ``str`` object encoded in the
default system encoding (usually means ASCII). If ``default`` is
``None`` (its default value), the ``msgid`` value used by this
translation string will be assumed to be the value of ``default``.
``mapping``, if supplied, must be a dictionary-like object which
represents the replacement values for any :term:`translation
string` *replacement marker* instances found within the ``msgid``
(or ``default``) value of this translation string.
``context`` represents the :term:`translation context`. By default,
the translation context is ``None``.
After a translation string is constructed, it behaves like most
other ``unicode`` objects; its ``msgid`` value will be displayed
when it is treated like a ``unicode`` object. Only when its
``ugettext`` method is called will it be translated.
Its default value is available as the ``default`` attribute of the
object, its :term:`translation domain` is available as the
``domain`` attribute, and the ``mapping`` is available as the
``mapping`` attribute. The object otherwise behaves much like a
Unicode string.
"""
__slots__ = ('domain', 'context', 'default', 'mapping')
def __new__(self, msgid, domain=None, default=None, mapping=None, context=None):
# NB: this function should never never lose the *original
# identity* of a non-``None`` but empty ``default`` value
# provided to it. See the comment in ChameleonTranslate.
self = text_type.__new__(self, msgid)
if isinstance(msgid, self.__class__):
domain = domain or msgid.domain and msgid.domain[:]
context = context or msgid.context and msgid.context[:]
default = default or msgid.default and msgid.default[:]
if msgid.mapping:
if mapping:
for k, v in msgid.mapping.items():
mapping.setdefault(k, v)
else:
mapping = msgid.mapping.copy()
msgid = text_type(msgid)
self.domain = domain
self.context = context
if default is None:
default = text_type(msgid)
self.default = default
self.mapping = mapping
return self
def __mod__(self, options):
"""Create a new TranslationString instance with an updated mapping.
This makes it possible to use the standard python %-style string
formatting with translatable strings. Only dictionary
arguments are supported.
"""
if not isinstance(options, dict):
raise ValueError(
'Can only interpolate translationstring '
'with dictionaries.')
if self.mapping:
mapping = self.mapping.copy()
mapping.update(options)
else:
mapping = options.copy()
return TranslationString(self, mapping=mapping)
def interpolate(self, translated=None):
""" Interpolate the value ``translated`` which is assumed to
be a Unicode object containing zero or more *replacement
markers* (``$foo`` or ``${bar}``) using the ``mapping``
dictionary attached to this instance. If the ``mapping``
dictionary is empty or ``None``, no interpolation is
performed.
If ``translated`` is ``None``, interpolation will be performed
against the ``default`` value.
"""
if translated is None:
translated = self.default
# NB: this function should never never lose the *original
# identity* of a non-``None`` but empty ``default`` value it
# is provided. If (translated == default) , it should return the
# *original* default, not a derivation. See the comment below in
# ChameleonTranslate.
if self.mapping and translated:
def replace(match):
whole, param1, param2 = match.groups()
return text_type(self.mapping.get(param1 or param2, whole))
translated = _interp_regex.sub(replace, translated)
return translated
def __reduce__(self):
return self.__class__, self.__getstate__()
def __getstate__(self):
return text_type(self), self.domain, self.default, self.mapping, self.context
[docs]
def TranslationStringFactory(factory_domain):
""" Create a factory which will generate translation strings
without requiring that each call to the factory be passed a
``domain`` value. A single argument is passed to this class'
constructor: ``domain``. This value will be used as the
``domain`` values of :class:`translationstring.TranslationString`
objects generated by the ``__call__`` of this class. The
``msgid``, ``mapping``, and ``default`` values provided to the
``__call__`` method of an instance of this class have the meaning
as described by the constructor of the
:class:`translationstring.TranslationString`"""
def create(msgid, mapping=None, default=None, context=None):
""" Provided a msgid (Unicode object or :term:`translation
string`) and optionally a mapping object, and a *default
value*, return a :term:`translation string` object."""
# if we are passing in a TranslationString as the msgid, then
# use its domain
if isinstance(msgid, TranslationString):
domain = msgid.domain or factory_domain
else:
domain = factory_domain
return TranslationString(msgid, domain=domain, default=default,
mapping=mapping, context=context)
return create
def ChameleonTranslate(translator):
"""
When necessary, use the result of calling this function as a
Chameleon template 'translate' function (e.g. the ``translate``
argument to the ``chameleon.zpt.template.PageTemplate``
constructor) to allow our translation machinery to drive template
translation. A single required argument ``translator`` is
passsed. The ``translator`` provided should be a callable which
accepts a single argument ``translation_string`` ( a
:class:`translationstring.TranslationString` instance) which
returns a ``unicode`` object as a translation. ``translator`` may
also optionally be ``None``, in which case no translation is
performed (the ``msgid`` or ``default`` value is returned
untranslated).
"""
def translate(msgid, domain=None, mapping=None, context=None,
target_language=None, default=None):
# NB: note that both TranslationString._init__ and
# TranslationString.interpolate are careful to never lose the
# *identity* of an empty but non-``None`` ``default`` value we
# provide to them. For example, neither of those functions
# are permitted to run an empty but non-``None`` ``default``
# through ``unicode`` and throw the original default value
# away afterwards.
# This has a dubious cause: for Chameleon API reasons we must
# ensure that, after translation, if ( (translated == msgid)
# and (not default) and (default is not None) ) that we return
# the ``default`` value provided to us *unmodified*, because
# Chameleon uses it as a sentinel (it compares the return
# value of this function by identity to what it passed in as
# ``default``; this marker is a
# chameleon.core.i18n.StringMarker instance, a subclass of str
# that == ''). This is, of course, totally absurd, because
# Chameleon *also* wants us to use ``default`` as the input to
# a translation string in some cases, and maintaining the
# identity of this object through translation operations isn't
# a contract it spells out in its docs.
# Chameleon's use of ``default`` to represent both a sentinel
# and input to a translation string is a Chameleon i18n
# extensibility design bug. Until we overhaul its hook point
# for translation extensibility, we need to appease it by
# preserving ``default`` in the aforementioned case. So we
# spray these indignant comments all over this module. ;-)
if not isinstance(msgid, string_types):
if msgid is not None:
msgid = text_type(msgid)
return msgid
tstring = msgid
if not hasattr(tstring, 'interpolate'):
tstring = TranslationString(msgid, domain, default, mapping, context)
if translator is None:
result = tstring.interpolate()
else:
result = translator(tstring)
return result
return translate
def ugettext_policy(translations, tstring, domain, context):
""" A translator policy function which unconditionally uses the
``ugettext`` API on the translations object."""
if PY3: # pragma: no cover
_gettext = translations.gettext
else: # pragma: no cover
_gettext = translations.ugettext
if context:
# Workaround for http://bugs.python.org/issue2504?
msgid = CONTEXT_MASK % (context, tstring)
else:
msgid = tstring
translated = _gettext(msgid)
return tstring if translated == msgid else translated
def dugettext_policy(translations, tstring, domain, context):
""" A translator policy function which assumes the use of a
:class:`babel.support.Translations` translations object, which
supports the dugettext API; fall back to ugettext."""
if domain is None:
default_domain = getattr(translations, 'domain', None) or 'messages'
domain = getattr(tstring, 'domain', None) or default_domain
context = context or getattr(tstring, 'context', None)
if context:
# Workaround for http://bugs.python.org/issue2504?
msgid = CONTEXT_MASK % (context, tstring)
else:
msgid = tstring
if getattr(translations, 'dugettext', None) is not None:
translated = translations.dugettext(domain, msgid)
else:
if PY3: # pragma: no cover
_gettext = translations.gettext
else: # pragma: no cover
_gettext = translations.ugettext
translated = _gettext(msgid)
return tstring if translated == msgid else translated
def Translator(translations=None, policy=None):
"""
Return a translator object based on the ``translations`` and
``policy`` provided. ``translations`` should be an object
supporting *at least* the Python :class:`gettext.NullTranslations`
API but ideally the :class:`babel.support.Translations` API, which
has support for domain lookups like dugettext.
``policy`` should be a callable which accepts three arguments:
``translations``, ``tstring`` and ``domain``. It must perform the
actual translation lookup. If ``policy`` is ``None``, the
:func:`translationstring.dugettext_policy` policy will be used.
The callable returned accepts three arguments: ``tstring``
(required), ``domain`` (optional) and ``mapping`` (optional).
When called, it will translate the ``tstring`` translation string
to a ``unicode`` object using the ``translations`` provided. If
``translations`` is ``None``, the result of interpolation of the
default value is returned. The optional ``domain`` argument can
be used to specify or override the domain of the ``tstring``
(useful when ``tstring`` is a normal string rather than a
translation string). The optional ``mapping`` argument can
specify or override the ``tstring`` interpolation mapping, useful
when the ``tstring`` argument is a simple string instead of a
translation string.
"""
if policy is None:
policy = dugettext_policy
def translator(tstring, domain=None, mapping=None, context=None):
if not hasattr(tstring, 'interpolate'):
tstring = TranslationString(tstring, domain=domain, mapping=mapping, context=context)
elif mapping:
if tstring.mapping:
new_mapping = tstring.mapping.copy()
new_mapping.update(mapping)
else:
new_mapping = mapping
tstring = TranslationString(tstring, domain=domain, mapping=new_mapping, context=context)
translated = tstring
domain = domain or tstring.domain
context = context or tstring.context
if translations is not None:
translated = policy(translations, tstring, domain, context)
if translated == tstring:
translated = tstring.default
if translated and '$' in translated and tstring.mapping:
translated = tstring.interpolate(translated)
return translated
return translator
def ungettext_policy(translations, singular, plural, n, domain, context):
""" A pluralizer policy function which unconditionally uses the
``ungettext`` API on the translations object."""
if PY3: # pragma: no cover
_gettext = translations.ngettext
else: # pragma: no cover
_gettext = translations.ungettext
if context:
# Workaround for http://bugs.python.org/issue2504?
msgid = CONTEXT_MASK % (context, singular)
else:
msgid = singular
translated = _gettext(msgid, plural, n)
return singular if translated == msgid else translated
def dungettext_policy(translations, singular, plural, n, domain, context):
""" A pluralizer policy function which assumes the use of the
:class:`babel.support.Translations` class, which supports the
dungettext API; falls back to ungettext."""
default_domain = getattr(translations, 'domain', None) or 'messages'
domain = domain or default_domain
if context:
# Workaround for http://bugs.python.org/issue2504?
msgid = CONTEXT_MASK % (context, singular)
else:
msgid = singular
if getattr(translations, 'dungettext', None) is not None:
translated = translations.dungettext(domain, msgid, plural, n)
else:
if PY3: # pragma: no cover
_gettext = translations.ngettext
else: # pragma: no cover
_gettext = translations.ungettext
translated = _gettext(msgid, plural, n)
return singular if translated == msgid else translated
def Pluralizer(translations=None, policy=None):
"""
Return a pluralizer object based on the ``translations`` and
``policy`` provided. ``translations`` should be an object
supporting *at least* the Python :class:`gettext.NullTranslations`
API but ideally the :class:`babel.support.Translations` API, which
has support for domain lookups like dugettext.
``policy`` should be a callable which accepts five arguments:
``translations``, ``singular`` and ``plural``, ``n`` and
``domain``. It must perform the actual pluralization lookup. If
``policy`` is ``None``, the
:func:`translationstring.dungettext_policy` policy will be used.
The object returned will be a callable which has the following
signature::
def pluralizer(singular, plural, n, domain=None, mapping=None):
...
The ``singular`` and ``plural`` objects passed may be translation
strings or unicode strings. ``n`` represents the number of
elements. ``domain`` is the translation domain to use to do the
pluralization, and ``mapping`` is the interpolation mapping that
should be used on the result. Note that if the objects passed are
translation strings, their domains and mappings are ignored. The
domain and mapping arguments must be used instead. If the ``domain`` is
not supplied, a default domain is used (usually ``messages``).
"""
if policy is None:
policy = dungettext_policy
if translations is None:
translations = NullTranslations()
def pluralizer(singular, plural, n, domain=None, mapping=None, context=None):
""" Pluralize this object """
translated = text_type(
policy(translations, singular, plural, n, domain, context))
if translated and '$' in translated and mapping:
return TranslationString(translated, mapping=mapping).interpolate()
return translated
return pluralizer
