translationstring

Warnings

• breaking 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.
  Fix: Upgrade to Python 3.4+ or ensure Python environment is compatible with `translationstring` 1.4 requirements.
• gotcha 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.
  Fix: Ensure that if `default` has interpolation markers, `msgid` is a simple identifier (e.g., `TranslationString('add-number', default='Add ${number}', mapping={'number':1})`).
• gotcha 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.
  Fix: Always pass `TranslationString` instances through a `Translator` callable or explicitly call their `ugettext` method to ensure they are translated and interpolated as intended.
• gotcha 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.
  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`.
• gotcha 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.
  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.

Install

• pip install translationstring PyPI

Imports

• TranslationString

  from translationstring import TranslationString

• TranslationStringFactory

  from translationstring import TranslationStringFactory

• Translator

  from translationstring import Translator

Quickstart

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.

import gettext
from translationstring import TranslationString, TranslationStringFactory, Translator

# 1. Create a mock translations object (e.g., from gettext or Babel)
# In a real app, this would load .mo files for a specific locale.
class MockTranslations(gettext.NullTranslations):
    def ugettext(self, message):
        # Simulate a translation, for demo just uppercase it if in 'app' domain
        # In a real scenario, this would look up in a catalog.
        if self.domain == 'app' and message == 'Hello':
            return 'Bonjour'
        return message
    
    def ungettext(self, singular, plural, n):
        if self.domain == 'app' and singular == '${num} item':
            if n == 1: return '${num} article'
            else: return '${num} articles'
        return super().ungettext(singular, plural, n)

mock_translations = MockTranslations()
mock_translations.add_domain('app')
mock_translations.set_output_charset('utf-8')

# 2. Create a Translator callable from the translations object
translator_callable = Translator(mock_translations)

# 3. Use TranslationString for individual strings
ts_hello = TranslationString('Hello', domain='app')
ts_item_plural = TranslationString('${num} item', plural='${num} items', mapping={'num': 1}, domain='app')
ts_item_plural_many = TranslationString('${num} item', plural='${num} items', mapping={'num': 5}, domain='app')

print(f"Raw TranslationString (no explicit translation): {ts_hello}")
print(f"Translated via callable: {transl_hello = translator_callable(ts_hello)}")
print(f"Plural translated (1 item): {transl_plural_1 = translator_callable(ts_item_plural, n=1)}")
print(f"Plural translated (5 items): {transl_plural_5 = translator_callable(ts_item_plural_many, n=5)}")

# 4. Use TranslationStringFactory for domain-prefixed strings (common convention is to assign to '_')
_ = TranslationStringFactory('app')
ts_factory_example = _('Welcome', default='Welcome to our application!')
print(f"Factory string (no translation in mock): {transl_welcome = translator_callable(ts_factory_example)}")

# Demonstrate interpolation
ts_interp = TranslationString('Hello ${name}', mapping={'name': 'World'})
print(f"Interpolated string: {transl_interp = translator_callable(ts_interp)}")