{"id":2816,"library":"translationstring","title":"translationstring","description":"Translationstring is a utility library for internationalization (i18n) primarily used by various Repoze and Pyramid packages. It provides core components like a `TranslationString` class, a `TranslationStringFactory` for creating translation strings, and primitives for translation and pluralization. These objects behave like Unicode strings but carry additional metadata for higher-level translation systems. The current version is 1.4, and it appears to be in maintenance mode, with its last release in July 2020.","status":"maintenance","version":"1.4","language":"en","source_language":"en","source_url":"https://github.com/Pylons/translationstring","tags":["i18n","internationalization","localization","pyramid","pylons"],"install":[{"cmd":"pip install translationstring","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Its translation and pluralization services are meant to work best when provided with an instance of `babel.support.Translations` for advanced features beyond basic `gettext.NullTranslations`.","package":"Babel","optional":true}],"imports":[{"symbol":"TranslationString","correct":"from translationstring import TranslationString"},{"symbol":"TranslationStringFactory","correct":"from translationstring import TranslationStringFactory"},{"symbol":"Translator","correct":"from translationstring import Translator"}],"quickstart":{"code":"import gettext\nfrom translationstring import TranslationString, TranslationStringFactory, Translator\n\n# 1. Create a mock translations object (e.g., from gettext or Babel)\n# In a real app, this would load .mo files for a specific locale.\nclass MockTranslations(gettext.NullTranslations):\n    def ugettext(self, message):\n        # Simulate a translation, for demo just uppercase it if in 'app' domain\n        # In a real scenario, this would look up in a catalog.\n        if self.domain == 'app' and message == 'Hello':\n            return 'Bonjour'\n        return message\n    \n    def ungettext(self, singular, plural, n):\n        if self.domain == 'app' and singular == '${num} item':\n            if n == 1: return '${num} article'\n            else: return '${num} articles'\n        return super().ungettext(singular, plural, n)\n\nmock_translations = MockTranslations()\nmock_translations.add_domain('app')\nmock_translations.set_output_charset('utf-8')\n\n# 2. Create a Translator callable from the translations object\ntranslator_callable = Translator(mock_translations)\n\n# 3. Use TranslationString for individual strings\nts_hello = TranslationString('Hello', domain='app')\nts_item_plural = TranslationString('${num} item', plural='${num} items', mapping={'num': 1}, domain='app')\nts_item_plural_many = TranslationString('${num} item', plural='${num} items', mapping={'num': 5}, domain='app')\n\nprint(f\"Raw TranslationString (no explicit translation): {ts_hello}\")\nprint(f\"Translated via callable: {transl_hello = translator_callable(ts_hello)}\")\nprint(f\"Plural translated (1 item): {transl_plural_1 = translator_callable(ts_item_plural, n=1)}\")\nprint(f\"Plural translated (5 items): {transl_plural_5 = translator_callable(ts_item_plural_many, n=5)}\")\n\n# 4. Use TranslationStringFactory for domain-prefixed strings (common convention is to assign to '_')\n_ = TranslationStringFactory('app')\nts_factory_example = _('Welcome', default='Welcome to our application!')\nprint(f\"Factory string (no translation in mock): {transl_welcome = translator_callable(ts_factory_example)}\")\n\n# Demonstrate interpolation\nts_interp = TranslationString('Hello ${name}', mapping={'name': 'World'})\nprint(f\"Interpolated string: {transl_interp = translator_callable(ts_interp)}\")","lang":"python","description":"This quickstart demonstrates how to use `TranslationString` and `TranslationStringFactory` to mark translatable text, and then how to use a `Translator` object to process them. It includes an example with a mock `gettext.NullTranslations` instance to simulate translation, showing singular/plural forms and interpolation."},"warnings":[{"fix":"Upgrade to Python 3.4+ or ensure Python environment is compatible with `translationstring` 1.4 requirements.","message":"Version 1.4 of `translationstring` dropped support for Python 2.6, 3.2, and 3.3. Projects using these older Python versions will need to stick to an earlier `translationstring` version or upgrade their Python environment.","severity":"breaking","affected_versions":"<=1.3"},{"fix":"Ensure that if `default` has interpolation markers, `msgid` is a simple identifier (e.g., `TranslationString('add-number', default='Add ${number}', mapping={'number':1})`).","message":"When using the `TranslationString` constructor with both `msgid` and `default`, if `default` contains replacement markers (e.g., `${number}`), then the `msgid` should *not* contain replacement markers. This is a common pattern for 'opaque' message identifiers.","severity":"gotcha","affected_versions":"All"},{"fix":"Always pass `TranslationString` instances through a `Translator` callable or explicitly call their `ugettext` method to ensure they are translated and interpolated as intended.","message":"A `TranslationString` object, when treated like a normal string, will display its `msgid` value. Actual translation (and interpolation of `mapping` values) only occurs when its `ugettext` method is called or when it's passed through a `translationstring.Translator` callable.","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of the parameter precedence. If you want to force a specific domain or mapping for a translation, pass them directly to the `Translator` callable. If the `TranslationString` itself holds the correct context, ensure no conflicting arguments are passed to the `Translator`.","message":"When passing a `TranslationString` to a `Translator` callable, any `domain` or `mapping` arguments provided directly to the `Translator` will override or combine with the `domain` and `mapping` attributes already present on the `TranslationString` instance.","severity":"gotcha","affected_versions":"All"},{"fix":"Follow the convention of `_ = TranslationStringFactory('your_domain')` for consistency and tooling compatibility, but remember that `_` is just a variable name and can be overridden.","message":"The package encourages the convention of assigning a `TranslationStringFactory` instance to the variable `_` (e.g., `_ = TranslationStringFactory('mydomain')`). This is a common `gettext` convention and is often supported by translation file generation tools.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}