translationstring-1.1/0000775000175000017500000000000011714422001016266 5ustar wichertwichert00000000000000translationstring-1.1/README.txt0000664000175000017500000000142211714421674020002 0ustar wichertwichert00000000000000translationstring ================= A library used by various `Pylons Project `_ packages for internationalization (i18n) duties related to translation. This package provides a *translation string* class, a *translation string factory* class, translation and pluralization primitives, and a utility that helps `Chameleon `_ templates use translation facilities of this package. It does not depend on `Babel `_, but its translation and pluralization services are meant to work best when provided with an instance of the ``babel.support.Translations`` class. Please see http://docs.pylonsproject.org/projects/translationstring/dev/ or the ``docs/index.rst`` file in this package for the documentation. translationstring-1.1/translationstring.egg-info/0000775000175000017500000000000011714422001023545 5ustar wichertwichert00000000000000translationstring-1.1/translationstring.egg-info/SOURCES.txt0000664000175000017500000000156111714422001025434 0ustar wichertwichert00000000000000CHANGES.txt CONTRIBUTORS.txt COPYRIGHT.txt LICENSE.txt MANIFEST.in README.txt setup.cfg setup.py tox.ini docs/.gitignore docs/Makefile docs/api.rst docs/chameleon.rst docs/conf.py docs/glossary.rst docs/index.rst docs/pluralization.rst docs/translation.rst docs/tstrings.rst docs/.static/logo_hi.gif docs/.static/repoze.css translationstring/__init__.py translationstring/compat.py translationstring.egg-info/PKG-INFO translationstring.egg-info/SOURCES.txt translationstring.egg-info/dependency_links.txt translationstring.egg-info/not-zip-safe translationstring.egg-info/top_level.txt translationstring/tests/__init__.py translationstring/tests/test__init__.py translationstring/tests/test_integration.py translationstring/tests/translations.py translationstring/tests/fixtures/locales/de/LC_MESSAGES/messages.mo translationstring/tests/fixtures/locales/de/LC_MESSAGES/messages.potranslationstring-1.1/translationstring.egg-info/dependency_links.txt0000664000175000017500000000000111714422001027613 0ustar wichertwichert00000000000000 translationstring-1.1/translationstring.egg-info/PKG-INFO0000664000175000017500000000741111714422001024645 0ustar wichertwichert00000000000000Metadata-Version: 1.0 Name: translationstring Version: 1.1 Summary: Utility library for i18n relied on by various Repoze and Pyramid packages Home-page: http://pylonsproject.org Author: Chris McDonough, Agendaless Consulting Author-email: pylons-discuss@googlegroups.com License: BSD-like (http://repoze.org/license.html) Description: translationstring ================= A library used by various `Pylons Project `_ packages for internationalization (i18n) duties related to translation. This package provides a *translation string* class, a *translation string factory* class, translation and pluralization primitives, and a utility that helps `Chameleon `_ templates use translation facilities of this package. It does not depend on `Babel `_, but its translation and pluralization services are meant to work best when provided with an instance of the ``babel.support.Translations`` class. Please see http://docs.pylonsproject.org/projects/translationstring/dev/ or the ``docs/index.rst`` file in this package for the documentation. translationstring ================= 1.1 (2012-02-08) ---------------- - Add MANIFEST to make sure all files are present in a release. This fixes `ticket 8 `_. 1.0 (2012-02-04) ---------------- - coerce non-string values to a string during translation, except for None. - Honour mapping information passed to the translator, combining it with mapping data already part of the translation string. - Support formatting of translation strings with %-operator. 0.4 (09-22-2011) ---------------- - Python 3 compatibility (thanks to Joe Dallago, GSOC student). - Remove testing dependency on Babel. - Moved to GitHub (https://github.com/Pylons/translationstring). - Added tox.ini for testing purposes. 0.3 (06-25-2010) ---------------- - Preserve default translations even if they are an empty string. This fixes problems with Chameleon being unable to determine if a translation is present or not. 0.2 (04-25-2010) ---------------- - Add ``__getstate__`` and ``__reduce__`` methods to translation string to allow for pickling. - Fix bug in ChameleonTranslate. When ``i18n:translate`` was used in templates, a translation string was inappropriately created with a ``default`` value of the empty string. Symptom: template text would "disappear" rather than being returned untranslated. 0.1 (04-24-2010) ---------------- - Initial release. Keywords: i18n l10n internationalization localization gettext chameleon Platform: UNKNOWN Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Developers Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.4 Classifier: Programming Language :: Python :: 2.5 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.2 Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: Software Development :: Internationalization Classifier: Topic :: Software Development :: Localization translationstring-1.1/translationstring.egg-info/top_level.txt0000664000175000017500000000002211714422001026271 0ustar wichertwichert00000000000000translationstring translationstring-1.1/translationstring.egg-info/not-zip-safe0000664000175000017500000000000111714421756026013 0ustar wichertwichert00000000000000 translationstring-1.1/MANIFEST.in0000664000175000017500000000027311714421674020045 0ustar wichertwichert00000000000000include *.txt include tox.ini recursive-include translationstring/tests/fixtures/locales *.mo recursive-include translationstring/tests/fixtures/locales *.po graft docs prune docs/_build translationstring-1.1/tox.ini0000664000175000017500000000116111714421674017617 0ustar wichertwichert00000000000000[tox] envlist = py24,py25,py26,py27,py32,jython,pypy,cover [testenv] commands = python setup.py test -q deps = Babel [testenv:jython] commands = jython setup.py test -q [testenv:cover] basepython = python2.6 commands = python setup.py nosetests --with-xunit --with-xcoverage deps = Babel nose coverage==3.4 nosexcover # we separate coverage into its own testenv because a) "last run wins" wrt # cobertura jenkins reporting and b) pypy and jython can't handle any # combination of versions of coverage and nosexcover that i can find. # coverage==3.4 is required by nosexcover. translationstring-1.1/LICENSE.txt0000664000175000017500000000337611714421674020141 0ustar wichertwichert00000000000000License A copyright notice accompanies this license document that identifies the copyright holders. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions in source code must retain the accompanying copyright notice, this list of conditions, and the following disclaimer. 2. Redistributions in binary form must reproduce the accompanying copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Names of the copyright holders must not be used to endorse or promote products derived from this software without prior written permission from the copyright holders. 4. If any files are modified, you must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. Disclaimer THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. translationstring-1.1/CHANGES.txt0000664000175000017500000000262011714421735020114 0ustar wichertwichert00000000000000translationstring ================= 1.1 (2012-02-08) ---------------- - Add MANIFEST to make sure all files are present in a release. This fixes `ticket 8 `_. 1.0 (2012-02-04) ---------------- - coerce non-string values to a string during translation, except for None. - Honour mapping information passed to the translator, combining it with mapping data already part of the translation string. - Support formatting of translation strings with %-operator. 0.4 (09-22-2011) ---------------- - Python 3 compatibility (thanks to Joe Dallago, GSOC student). - Remove testing dependency on Babel. - Moved to GitHub (https://github.com/Pylons/translationstring). - Added tox.ini for testing purposes. 0.3 (06-25-2010) ---------------- - Preserve default translations even if they are an empty string. This fixes problems with Chameleon being unable to determine if a translation is present or not. 0.2 (04-25-2010) ---------------- - Add ``__getstate__`` and ``__reduce__`` methods to translation string to allow for pickling. - Fix bug in ChameleonTranslate. When ``i18n:translate`` was used in templates, a translation string was inappropriately created with a ``default`` value of the empty string. Symptom: template text would "disappear" rather than being returned untranslated. 0.1 (04-24-2010) ---------------- - Initial release. translationstring-1.1/translationstring/0000775000175000017500000000000011714422001022053 5ustar wichertwichert00000000000000translationstring-1.1/translationstring/__init__.py0000664000175000017500000003726611714421674024221 0ustar wichertwichert00000000000000import 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'(?= 0.15) CONTEXT_ENCODING = '%s\x04%s' translationstring-1.1/translationstring/compat.py0000664000175000017500000000052611714421674023732 0ustar wichertwichert00000000000000import sys PY3 = sys.version_info[0] == 3 if PY3: # pragma: no cover string_types = (str,) text_type = str else: # pragma: no cover string_types = (basestring,) text_type = unicode if PY3: # pragma: no cover def u(s): return s else: # pragma: no cover def u(s): return unicode(s, 'unicode_escape') translationstring-1.1/PKG-INFO0000664000175000017500000000741111714422001017366 0ustar wichertwichert00000000000000Metadata-Version: 1.0 Name: translationstring Version: 1.1 Summary: Utility library for i18n relied on by various Repoze and Pyramid packages Home-page: http://pylonsproject.org Author: Chris McDonough, Agendaless Consulting Author-email: pylons-discuss@googlegroups.com License: BSD-like (http://repoze.org/license.html) Description: translationstring ================= A library used by various `Pylons Project `_ packages for internationalization (i18n) duties related to translation. This package provides a *translation string* class, a *translation string factory* class, translation and pluralization primitives, and a utility that helps `Chameleon `_ templates use translation facilities of this package. It does not depend on `Babel `_, but its translation and pluralization services are meant to work best when provided with an instance of the ``babel.support.Translations`` class. Please see http://docs.pylonsproject.org/projects/translationstring/dev/ or the ``docs/index.rst`` file in this package for the documentation. translationstring ================= 1.1 (2012-02-08) ---------------- - Add MANIFEST to make sure all files are present in a release. This fixes `ticket 8 `_. 1.0 (2012-02-04) ---------------- - coerce non-string values to a string during translation, except for None. - Honour mapping information passed to the translator, combining it with mapping data already part of the translation string. - Support formatting of translation strings with %-operator. 0.4 (09-22-2011) ---------------- - Python 3 compatibility (thanks to Joe Dallago, GSOC student). - Remove testing dependency on Babel. - Moved to GitHub (https://github.com/Pylons/translationstring). - Added tox.ini for testing purposes. 0.3 (06-25-2010) ---------------- - Preserve default translations even if they are an empty string. This fixes problems with Chameleon being unable to determine if a translation is present or not. 0.2 (04-25-2010) ---------------- - Add ``__getstate__`` and ``__reduce__`` methods to translation string to allow for pickling. - Fix bug in ChameleonTranslate. When ``i18n:translate`` was used in templates, a translation string was inappropriately created with a ``default`` value of the empty string. Symptom: template text would "disappear" rather than being returned untranslated. 0.1 (04-24-2010) ---------------- - Initial release. Keywords: i18n l10n internationalization localization gettext chameleon Platform: UNKNOWN Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Developers Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.4 Classifier: Programming Language :: Python :: 2.5 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.2 Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: Software Development :: Internationalization Classifier: Topic :: Software Development :: Localization translationstring-1.1/setup.py0000664000175000017500000000313311714421743020014 0ustar wichertwichert00000000000000import os from setuptools import setup from setuptools import find_packages here = os.path.abspath(os.path.dirname(__file__)) try: README = open(os.path.join(here, 'README.txt')).read() CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() except: README = '' CHANGES = '' setup(name='translationstring', version='1.1', description=('Utility library for i18n relied on by various Repoze ' 'and Pyramid packages'), long_description=README + '\n\n' + CHANGES, classifiers=[ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.4", "Programming Language :: Python :: 2.5", "Programming Language :: Python :: 2.6", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.2", "Topic :: Software Development :: Libraries :: Python Modules", "Topic :: Software Development :: Internationalization", "Topic :: Software Development :: Localization", ], keywords='i18n l10n internationalization localization gettext chameleon', author="Chris McDonough, Agendaless Consulting", author_email="pylons-discuss@googlegroups.com", url="http://pylonsproject.org", license="BSD-like (http://repoze.org/license.html)", packages=find_packages(), include_package_data=True, zip_safe=False, test_suite="translationstring", ) translationstring-1.1/docs/0000775000175000017500000000000011714422001017216 5ustar wichertwichert00000000000000translationstring-1.1/docs/.static/0000775000175000017500000000000011714422001020563 5ustar wichertwichert00000000000000translationstring-1.1/docs/.static/logo_hi.gif0000664000175000017500000000752411714421674022721 0ustar wichertwichert00000000000000GIF89a3BBBًzι<<>>ԾԾտѻԿLKIԶľBBA@@?|||??>AAAȼEEEHGEڷcccյųMMM˽͸̾vur@??YYYxCCCþihc:::ӽ!,3 H*\ȰÇ#JHŋ3jȱdžIrCȲ˅.ȜI^F͟?ѬIhE*XMJu! j%D. MjJ?_Ŗ@D|"݅t['Y EHG8._7CW"7)Tv'r֦+RcN+'n c ZMd#g׎9f _HrA\FSAUR`rMq`E"Wҥ&7ĄB5BU t fM?~O?5WGՂ|,ȢC4D54Xc8+pA , 9$ C- Cy  & E(q0 t$ ܴf(D.@>yXM4+ 7H‚JhTBE BZ0'@YN16tQbP X*:ab lTåuQf jJ dBDNC tP<P _PPRlpʴ ;D2$$aQCk72/Dx0(g& J#̐A:r AD!8(a 8žT4΃»@ 3(h.@B氽T@L;|B١sC@khQ:QęCt 0`=GJX-W|A !,@3zrasA rnqRh2[K\ Djئ<9E*Z8p@!p.n B x| ՐtS%=a,$`h %@A'6xB †) 6x;50bLPxF+90bA00)4l#QC-D&lp}PGvG<ڠ'cC!u!,._h ZN_a $ @Ҏ+P2R(ՇMosP/`qg.b Ed_ D 2,%vvm!^+P/yz"<S?yH€WPR C4;@`b9-@_0jj`!`\8lyxw WH0 `cPaQ 0$ W}GJ l   aCЍpqQ@PA dvyGP pYP E" (P{ 0@@ 1 F@d s @ 900) ٟ ;translationstring-1.1/docs/.static/repoze.css0000664000175000017500000000077511714421674022631 0ustar wichertwichert00000000000000@import url('default.css'); body { background-color: #006339; } div.document { background-color: #dad3bd; } div.sphinxsidebar h3, h4, h5, a { color: #127c56 !important; } div.related { color: #dad3bd !important; background-color: #00744a; } div.related a { color: #dad3bd !important; } /* override the justify text align of the default */ div.body p { text-align: left !important; } /* fix google chrome 
 tag renderings */

pre {
   line-height: normal !important;
}
translationstring-1.1/docs/index.rst0000664000175000017500000000147511714421674021105 0ustar  wichertwichert00000000000000translationstring
=================

A library used by various `Pylons Project `_
packages for internationalization (i18n) duties.

This package provides a :term:`translation string` class, a
:term:`translation string factory` class, translation and
pluralization primitives, and a utility that helps :term:`Chameleon`
templates use translation facilities of this package.  It does not
depend on :term:`Babel`, but its translation and pluralization
services are meant to work best when provided with an instance of the
:class:`babel.support.Translations` class.

.. toctree::
   :maxdepth: 2

   tstrings.rst
   translation.rst
   pluralization.rst
   chameleon.rst
   api.rst
   glossary.rst

Index and Glossary
==================

* :ref:`glossary`
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
translationstring-1.1/docs/translation.rst0000664000175000017500000000513511714421674022331 0ustar  wichertwichert00000000000000.. _translation_chapter:

Translation
===========

:mod:`translationstring` provides a function named
:func:`translationstring.Translator` which is used to create a
:term:`translator` object.

It is called like so:

.. code-block:: python
   :linenos:

   import gettext
   from translationstring import Translator
   translations = gettext.translations(.. the right arguments ...)
   translator = Translator(translations)

The ``translations`` argument is required; it 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.

The callable returned accepts three arguments: a translation string
``tstring`` (required), ``domain`` (optional), and ``mapping``
(optional).  When called, it will translate the ``tstring``
translation string to a ``unicode`` object using the ``translations``
object provided and interpolate the result.

.. code-block:: python
   :linenos:

   from gettext import translations
   from translationstring import Translator
   from translationstring import TranslationString

   t = translations(.. the right arguments ...)
   translator = Translator(t)
   ts = TranslationString('Add ${number}', domain='foo', mapping={'number':1})
   translator(ts)

If ``translations`` is ``None``, the result of interpolation of the
msgid or default value of the translation string is returned.

The translation function can also deal with plain Unicode objects.
The optional ``domain`` argument can be used to specify or override
the domain of the ``tstring`` argument (useful when ``tstring`` is a
normal string rather than a translation string).  The optional
``mapping`` argument can specify the interpolation mapping, useful
when the ``tstring`` argument is not a translation string. If 
``tstring`` is a translation string its mapping data, if present, is
combined with the data from the ``mapping`` argument.

.. code-block:: python
   :linenos:

   from gettext import translations
   from translationstring import Translator
   from translationstring import TranslationString

   t = translations(.. the right arguments ...)
   translator = Translator(t)
   translator('Add ${number}', domain='foo', mapping={'number':1})

The :func:`translationstring.Translator` function accepts an
additional optional argument named ``policy``.  ``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.

translationstring-1.1/docs/.gitignore0000664000175000017500000000001011714421674021214 0ustar  wichertwichert00000000000000_build/
translationstring-1.1/docs/glossary.rst0000664000175000017500000000504511714421674021636 0ustar  wichertwichert00000000000000.. _glossary:

Glossary
========

.. glossary::
   :sorted:

   Translation String
     An instance of :class:`translationstring.TranslationString`,
     which is a class that behaves like a Unicode string, but has
     several extra attributes such as ``domain``, ``msgid``, and
     ``mapping`` for use during translation.  Translation strings are
     usually created by hand within software, but are sometimes
     created on the behalf of the system for automatic template
     translation.  For more information, see
     :ref:`translationstring_module`.

   Translation String Factory
     A factory for generating :term:`translation string` objects which
     predefines a :term:`translation domain`.

   Translation Domain
     A string representing the "context" in which a particular
     translation was made.  For example the word "java" might be
     translated differently if the translation domain is
     "programming-languages" than would be if the translation domain
     was "coffee".  Every :term:`translation string` has an associated
     translation domain.

   Message Identifier
     An unchanging string that is the identifier for a particular
     translation string.  For example, you may have a translation
     string which has the ``default`` "the fox jumps over the lazy
     dog", but you might give this translation string a message
     identifier of ``foxdog`` to reduce the chances of minor spelling
     or wording changes breaking your translations.  The message
     identifier of a :term:`translation string` is represented as its
     ``msgid`` argument.

   Translation Directory
     A translation directory is a :term:`gettext` translation
     directory.  It contains language folders, which themselves
     contain ``LC_MESSAGES`` folders, which contain ``.mo`` files.
     Each ``.mo`` file represents a set of translations for a language
     in a :term:`translation domain`.  The name of the ``.mo`` file
     (minus the .mo extension) is the translation domain name.

   Gettext
     The GNU `gettext `_
     library, used by the :mod:`translationstring` locale translation
     machinery.

   Translator
     A callable which receives a :term:`translation string` and
     returns a translated Unicode object for the purposes of
     internationalization.  

   Babel
     A `collection of tools `_ for
     internationalizing Python applications.

   Chameleon
     `chameleon `_ is templating language
     written and maintained by Malthe Borch.
translationstring-1.1/docs/tstrings.rst0000664000175000017500000001643211714421674021652 0ustar  wichertwichert00000000000000.. _tstrings_chapter:

Translation Strings
===================

While you write your software, you can insert specialized markup into
your Python code that makes it possible for the system to translate
text values into the languages used by your application's users.  This
markup generates a :term:`translation string`.  A translation string
is an object that behave mostly like a normal Unicode object, except
that it also carries around extra information related to its job as
part of a higher-level system's translation machinery.

.. note:: Using a translation string can be thought of as equivalent
   to using a "lazy string" object in other i18n systems.

Using The ``TranslationString`` Class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The most primitive way to create a translation string is to use the
:class:`translationstring.TranslationString` callable:

.. code-block:: python
   :linenos:

   from translationstring import TranslationString
   ts = TranslationString('Add')

This creates a Unicode-like object that is a
:class:`translationstring.TranslationString`.

.. note::

   For people familiar with Zope internationalization, a
   TranslationString is a lot like a ``zope.i18nmessageid.Message``
   object.  It is not a subclass, however.

The first argument to :class:`translationstring.TranslationString` is the
``msgid``; it is required.  It represents the key into the translation
mappings provided by a particular localization. The ``msgid`` argument
must be a Unicode object or an ASCII string.  The msgid may optionally
contain *replacement markers*.  For instance:

.. code-block:: python
   :linenos:

   from translationstring import TranslationString
   ts = TranslationString('Add ${number}')

Within the string above, ``${stuff}`` is a replacement marker.  It
will be replaced by whatever is in the *mapping* for a translation
string when the :meth:`translationstring.TranslationString.interpolate` method
is called.  The mapping may be supplied at the same time as the
replacement marker itself:

.. code-block:: python
   :linenos:

   from translationstring import TranslationString
   ts = TranslationString('Add ${number}', mapping={'number':1})

You can also create a new translation string instance with a mapping
using the standard python %-operator:

.. code-block:: python
   :linenos:

   from translationstring import TranslationString
   ts = TranslationString('Add ${number}') % {'number': 1}

You may interpolate a translation string with a mapping:

.. code-block:: python
   :linenos:

   from translationstring import TranslationString
   ts = TranslationString('Add ${number}', mapping={'number':1})
   result = ts.interpolate()

The above ``result`` will be ``Add 1``.

Any number of replacement markers can be present in the msgid value,
any number of times.  Only markers which can be replaced by the values
in the *mapping* will be replaced at translation time.  The others
will not be interpolated and will be output literally.

Replacement markers may also be spelled without squiggly braces:

.. code-block:: python
   :linenos:

   from translationstring import TranslationString
   ts = TranslationString('Add $number', mapping={'number':1})

The ``Add $number`` msgid above is equivalent to ``Add ${number}``.

A translation string should also usually carry a *domain*.  The domain
represents a translation category to disambiguate it from other
translations of the same msgid, in case they conflict.

.. code-block:: python
   :linenos:

   from translationstring import TranslationString
   ts = TranslationString('Add ${number}', mapping={'number':1}, 
                          domain='form')

The above translation string named a domain of ``form``.  A
*translator* function (see :ref:`translation_chapter`) will often use
the domain to locate the right translator file on the filesystem which
contains translations for a given domain.  In this case, if it were
trying to translate to our msgid to German, it might try to find a
translation from a :term:`gettext` file within a :term:`translation
directory` like this one::

   locale/de/LC_MESSAGES/form.mo

In other words, it would want to take translations from the ``form.mo``
translation file in the German language.

Finally, the TranslationString constructor accepts a ``default``
argument.  If a ``default`` argument is supplied, it replaces usages
of the ``msgid`` as the *default value* for the translation string.
When ``default`` is ``None``, the ``msgid`` value passed to a
TranslationString is used as an implicit message identifier.  Message
identifiers are matched with translations in translation files, so it
is often useful to create translation strings with "opaque" message
identifiers unrelated to their default text:

.. code-block:: python
   :linenos:

   from translationstring import TranslationString
   ts = TranslationString('add-number', default='Add ${number}',
                           domain='form', mapping={'number':1})

When a ``default`` value is used, the default may contain replacement
markers and the msgid should not contain replacement markers.

Using the ``TranslationStringFactory`` Class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Another way to generate a translation string is to use the
:attr:`translationstring.TranslationStringFactory` object.  This object is a
*translation string factory*.  Basically a translation string factory
presets the ``domain`` value of any :term:`translation string`
generated by using it.  For example:

.. code-block:: python
   :linenos:

   from translationstring import TranslationStringFactory
   _ = TranslationStringFactory('bfg')
   ts = _('add-number', default='Add ${number}', mapping={'number':1})

.. note:: We assigned the translation string factory to the name
   ``_``.  This is a convention which will be supported by translation
   file generation tools.

After assigning ``_`` to the result of a
:func:`translationstring.TranslationStringFactory`, the subsequent
result of calling ``_`` will be a
:class:`translationstring.TranslationString` instance.  Even though a
``domain`` value was not passed to ``_`` (as would have been necessary
if the :class:`translationstring.TranslationString` constructor were
used instead of a translation string factory), the ``domain``
attribute of the resulting translation string will be ``bfg``.  As a
result, the previous code example is completely equivalent (except for
spelling) to:

.. code-block:: python
   :linenos:

   from translationstring import TranslationString as _
   ts = _('add-number', default='Add ${number}', mapping={'number':1}, 
          domain='bfg')

You can set up your own translation string factory much like the one
provided above by using the
:class:`translationstring.TranslationStringFactory` class.  For example,
if you'd like to create a translation string factory which presets the
``domain`` value of generated translation strings to ``form``, you'd
do something like this:

.. code-block:: python
   :linenos:

   from translationstring import TranslationStringFactory
   _ = TranslationStringFactory('form')
   ts = _('add-number', default='Add ${number}', mapping={'number':1})

.. note::

   For people familiar with Zope internationalization, a
   TranslationStringFactory is a lot like a
   ``zope.i18nmessageid.MessageFactoy`` object.  It is not a subclass,
   however.

Pickleability
-------------

Translation strings may be pickled and unpickled.
translationstring-1.1/docs/api.rst0000664000175000017500000000071111714421674020537 0ustar  wichertwichert00000000000000.. _translationstring_module:

API Documentation
-----------------

.. automodule:: translationstring

  .. autoclass:: TranslationString
     :members:
 
  .. autofunction:: TranslationStringFactory

  .. autofunction:: ChameleonTranslate

  .. autofunction:: Translator

  .. autofunction:: dugettext_policy

  .. autofunction:: ugettext_policy

  .. autofunction:: Pluralizer

  .. autofunction:: dungettext_policy

  .. autofunction:: ungettext_policy

translationstring-1.1/docs/Makefile0000664000175000017500000000532011714421674020675 0ustar  wichertwichert00000000000000# Makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
PAPER         =

# Internal variables.
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html web pickle htmlhelp latex changes linkcheck

help:
	@echo "Please use \`make ' where  is one of"
	@echo "  html      to make standalone HTML files"
	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
	@echo "  htmlhelp  to make HTML files and a HTML help project"
	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
	@echo "  changes   to make an overview over all changed/added/deprecated items"
	@echo "  linkcheck to check all external links for integrity"

clean:
	-rm -rf _build/*

html: _themes
	mkdir -p _build/html _build/doctrees
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
	@echo
	@echo "Build finished. The HTML pages are in _build/html."

text:
	mkdir -p _build/text _build/doctrees
	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
	@echo
	@echo "Build finished. The HTML pages are in _build/text."

pickle:
	mkdir -p _build/pickle _build/doctrees
	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
	@echo
	@echo "Build finished; now you can process the pickle files or run"
	@echo "  sphinx-web _build/pickle"
	@echo "to start the sphinx-web server."

web: pickle

htmlhelp: _themes
	mkdir -p _build/htmlhelp _build/doctrees
	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
	@echo
	@echo "Build finished; now you can run HTML Help Workshop with the" \
	      ".hhp project file in _build/htmlhelp."

latex:
	mkdir -p _build/latex _build/doctrees
	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
	cp _static/*.png _build/latex
	./convert_images.sh
	cp _static/latex-warning.png _build/latex
	cp _static/latex-note.png _build/latex
	@echo
	@echo "Build finished; the LaTeX files are in _build/latex."
	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
	      "run these through (pdf)latex."

changes:
	mkdir -p _build/changes _build/doctrees
	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
	@echo
	@echo "The overview file is in _build/changes."

linkcheck:
	mkdir -p _build/linkcheck _build/doctrees
	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
	@echo
	@echo "Link check complete; look for any errors in the above output " \
	      "or in _build/linkcheck/output.txt."

epub:
	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) _build/epub
	@echo
	@echo "Build finished. The epub file is in _build/epub."

_themes:
	cd ..; git submodule update --init; cd docs
translationstring-1.1/docs/conf.py0000664000175000017500000001416111714421674020537 0ustar  wichertwichert00000000000000# -*- coding: utf-8 -*-
#
# translationstring documentation build configuration file
#
# This file is execfile()d with the current directory set to its containing
# dir.
#
# The contents of this file are pickled, so don't put values in the
# namespace that aren't pickleable (module imports are okay, they're
# removed automatically).
#
# All configuration values have a default value; values that are commented
# out serve to show the default value.

import sys, os

# If your extensions are in another directory, add it here. If the
# directory is relative to the documentation root, use os.path.abspath to
# make it absolute, like shown here.
#sys.path.append(os.path.abspath('some/directory'))

parent = os.path.dirname(os.path.dirname(__file__))
sys.path.append(os.path.abspath(parent))
wd = os.getcwd()
os.chdir(parent)
os.system('%s setup.py test -q' % sys.executable)
os.chdir(wd)

for item in os.listdir(parent):
    if item.endswith('.egg'):
        sys.path.append(os.path.join(parent, item))


# General configuration
# ---------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc']

# Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates']

# The suffix of source filenames.
source_suffix = '.rst'

# The master toctree document.
master_doc = 'index'

# General substitutions.
project = 'translationstring'
copyright = '2011, Agendaless Consulting '

# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
#
# The short X.Y version.
version = '0.4'
# The full version, including alpha/beta/rc tags.
release = version

# There are two options for replacing |today|: either, you set today to
# some non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
today_fmt = '%B %d, %Y'

# List of documents that shouldn't be included in the build.
#unused_docs = []

# List of directories, relative to source directories, that shouldn't be
# searched for source files.
#exclude_dirs = []

# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'


# Options for HTML output
# -----------------------

sys.path.append(os.path.abspath('_themes'))
html_theme_path = ['_themes']
html_theme = 'pyramid'
html_theme_options = dict(github_url='https://github.com/Pylons/translationstring')


# The style sheet to use for HTML and HTML Help pages. A file of that name
# must exist either in Sphinx' static/ path, or in one of the custom paths
# given in html_static_path.
#html_style = 'pylons.css'

# The name for this set of Sphinx documents.  If None, it defaults to
# " v documentation".
#html_title = None

# A shorter title for the navigation bar.  Default is the same as
# html_title.
#html_short_title = None

# The name of an image file (within the static path) to place at the top of
# the sidebar.
html_logo = '.static/logo_hi.gif'

# The name of an image file (within the static path) to use as favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or
# 32x32 pixels large.
#html_favicon = None

# Add any paths that contain custom static files (such as style sheets)
# here, relative to this directory. They are copied after the builtin
# static files, so a file named "default.css" will overwrite the builtin
# "default.css".
#html_static_path = ['.static']

# If not '', a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}

# If false, no module index is generated.
#html_use_modindex = True

# If false, no index is generated.
#html_use_index = True

# If true, the index is split into individual pages for each letter.
#html_split_index = False

# If true, the reST sources are included in the HTML build as
# _sources/.
#html_copy_source = True

# If true, an OpenSearch description file will be output, and all pages
# will contain a  tag referring to it.  The value of this option must
# be the base URL from which the finished HTML is served.
#html_use_opensearch = ''

# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''

# Output file base name for HTML help builder.
htmlhelp_basename = 'translationstringdoc'


# Options for LaTeX output
# ------------------------

# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'

# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, document class [howto/manual]).
latex_documents = [
  ('index', 'translationstring.tex', 'translationstring Documentation',
   'Pylons Developers', 'manual'),
]

# The name of an image file (relative to this directory) to place at the
# top of the title page.
latex_logo = '.static/logo_hi.gif'

# For "manual" documents, if this is true, then toplevel headings are
# parts, not chapters.
#latex_use_parts = False

# Additional stuff for the LaTeX preamble.
#latex_preamble = ''

# Documents to append as an appendix to all manuals.
#latex_appendices = []

# If false, no module index is generated.
#latex_use_modindex = True
translationstring-1.1/docs/chameleon.rst0000664000175000017500000000207211714421674021723 0ustar  wichertwichert00000000000000Chameleon Translate Function Support
=====================================

:func:`translationstring.ChameleonTranslate` is a function which
returns a callable suitable for use as the ``translate`` argument to
various ``PageTemplate*`` constructors.

.. code-block:: python
   :linenos:

   from chameleon.zpt.template import PageTemplate
   from translationstring import ChameleonTranslate
   from translationstring import Translator
   import gettext

   translations = gettext.translations(...)
   translator = Translator(translations)
   translate = ChameleonTranslate(translate)
   pt = PageTemplate('', translate=translate)

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; usually the result of calling
:func:`translationstring.Translator`.  ``translator`` may also
optionally be ``None``, in which case no translation is performed (the
``msgid`` or ``default`` value is returned untranslated).
translationstring-1.1/docs/pluralization.rst0000664000175000017500000000362511714421674022672 0ustar  wichertwichert00000000000000Pluralization
=============

:func:`translationstring.Pluralizer` provides a gettext "plural forms"
pluralization service.

It is called like so:

.. code-block:: python
   :linenos:

   import gettext
   from translationstring import Pluralizer
   translations = gettext.translations(.. the right arguments ...)
   pluralizer = Pluralizer(translations)

The ``translations`` argument is required; it 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 dungettext.

The object returned will be a callable which has the following
signature:

.. code-block:: python
   :linenos:

   def pluralizer(singular, plural, n, domain=None, mapping=None):
       """ Pluralize """

The ``singular`` and ``plural`` arguments 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.  The pluralizer will return the plural form or the
singular form, translated, as necessary.

.. note:: 

  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 ``translations`` is ``None``, a :class:`gettext.NullTranslations`
object is created for the pluralizer to use.

The :func:`translationstring.Pluralizer` function accepts an
additional optional argument named ``policy``.  ``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.

translationstring-1.1/setup.cfg0000664000175000017500000000031711714422001020110 0ustar  wichertwichert00000000000000[easy_install]
zip_ok = false

[nosetests]
match = ^test
where = translationstring
nocapture = 1
cover-package = translationstring
cover-erase = 1

[egg_info]
tag_build = 
tag_date = 0
tag_svn_revision = 0

translationstring-1.1/CONTRIBUTORS.txt0000664000175000017500000001106311714421674021004 0ustar  wichertwichert00000000000000Pylons Project Contributor Agreement
====================================

The submitter agrees by adding his or her name within the section below named
"Contributors" and submitting the resulting modified document to the
canonical shared repository location for this software project (whether
directly, as a user with "direct commit access", or via a "pull request"), he
or she is signing a contract electronically.  The submitter becomes a
Contributor after a) he or she signs this document by adding their name
beneath the "Contributors" section below, and b) the resulting document is
accepted into the canonical version control repository.

Treatment of Account
---------------------

Contributor will not allow anyone other than the Contributor to use his or
her username or source repository login to submit code to a Pylons Project
source repository. Should Contributor become aware of any such use,
Contributor will immediately by notifying Agendaless Consulting.
Notification must be performed by sending an email to
webmaster@agendaless.com.  Until such notice is received, Contributor will be
presumed to have taken all actions made through Contributor's account. If the
Contributor has direct commit access, Agendaless Consulting will have
complete control and discretion over capabilities assigned to Contributor's
account, and may disable Contributor's account for any reason at any time.

Legal Effect of Contribution
----------------------------

Upon submitting a change or new work to a Pylons Project source Repository (a
"Contribution"), you agree to assign, and hereby do assign, a one-half
interest of all right, title and interest in and to copyright and other
intellectual property rights with respect to your new and original portions
of the Contribution to Agendaless Consulting. You and Agendaless Consulting
each agree that the other shall be free to exercise any and all exclusive
rights in and to the Contribution, without accounting to one another,
including without limitation, the right to license the Contribution to others
under the Repoze Public License. This agreement shall run with title to the
Contribution. Agendaless Consulting does not convey to you any right, title
or interest in or to the Program or such portions of the Contribution that
were taken from the Program. Your transmission of a submission to the Pylons
Project source Repository and marks of identification concerning the
Contribution itself constitute your intent to contribute and your assignment
of the work in accordance with the provisions of this Agreement.

License Terms
-------------

Code committed to the Pylons Project source repository (Committed Code) must
be governed by the Repoze Public License (http://repoze.org/LICENSE.txt, aka
"the RPL") or another license acceptable to Agendaless Consulting.  Until
Agendaless Consulting declares in writing an acceptable license other than
the RPL, only the RPL shall be used.  A list of exceptions is detailed within
the "Licensing Exceptions" section of this document, if one exists.

Representations, Warranty, and Indemnification
----------------------------------------------

Contributor represents and warrants that the Committed Code does not violate
the rights of any person or entity, and that the Contributor has legal
authority to enter into this Agreement and legal authority over Contributed
Code. Further, Contributor indemnifies Agendaless Consulting against
violations.

Cryptography
------------

Contributor understands that cryptographic code may be subject to government
regulations with which Agendaless Consulting and/or entities using Committed
Code must comply. Any code which contains any of the items listed below must
not be checked-in until Agendaless Consulting staff has been notified and has
approved such contribution in writing.

- Cryptographic capabilities or features

- Calls to cryptographic features

- User interface elements which provide context relating to cryptography

- Code which may, under casual inspection, appear to be cryptographic.

Notices
-------

Contributor confirms that any notices required will be included in any
Committed Code.

Licensing Exceptions
====================

None.

List of Contributors
====================

The below-signed are contributors to a code repository that is part of the
project named "Translationstring".  Each below-signed contributor has read, 
understands and agrees to the terms above in the section within this document
entitled "Pylons Project Contributor Agreement" as of the date beside his or 
her name.

Contributors
------------

- Chris McDonough, 2011/02/16
- Wichert Akkerman, 2012/02/02
translationstring-1.1/COPYRIGHT.txt0000664000175000017500000000015511714421674020417 0ustar  wichertwichert00000000000000Copyright (c) 2011 Agendaless Consulting and Contributors.
(http://www.agendaless.com), All Rights Reserved