oslo.i18n API¶

oslo_i18n¶

class oslo_i18n.TranslatorFactory(domain, localedir=None)¶

Create translator functions

contextual_form¶

The contextual translation function.

The returned function takes two values, the context of the unicode string, the unicode string to be translated.

New in version 2.1.0.

log_critical¶

Translate critical-level log messages.

log_error¶

Translate error-level log messages.

log_info¶

Translate info-level log messages.

log_warning¶

Translate warning-level log messages.

plural_form¶

The plural translation function.

The returned function takes three values, the single form of the unicode string, the plural form of the unicode string, the count of items to be translated.

New in version 2.1.0.

primary¶

The default translation function.

oslo_i18n.enable_lazy(enable=True)¶

Convenience function for configuring _() to use lazy gettext

Call this at the start of execution to enable the gettextutils._ function to use lazy gettext functionality. This is useful if your project is importing _ directly instead of using the gettextutils.install() way of importing the _ function.

Parameters:	enable (bool) – Flag indicating whether lazy translation should be turned on or off. Defaults to True.

oslo_i18n.translate(obj, desired_locale=None)¶

Gets the translated unicode representation of the given object.

If the object is not translatable it is returned as-is.

If the desired_locale argument is None the object is translated to the system locale.

Parameters:	obj – the object to translate desired_locale – the locale to translate the message to, if None the default system locale will be used
Returns:	the translated object in unicode, or the original object if it could not be translated

oslo_i18n.get_available_languages(domain)¶

Lists the available languages for the given translation domain.

Parameters:	domain – the domain to get languages for

oslo_i18n.log¶

logging utilities for translation

class oslo_i18n.log.TranslationHandler(locale=None, target=None)¶

Handler that translates records before logging them.

When lazy translation is enabled in the application (see enable_lazy()), the TranslationHandler uses its locale configuration setting to determine how to translate LogRecord objects before forwarding them to the logging.Handler.

When lazy translation is disabled, the message in the LogRecord is converted to unicode without any changes and then forwarded to the logging.Handler.

The handler can be configured declaratively in the logging.conf as follows:

[handlers]
keys = translatedlog, translator

[handler_translatedlog]
class = handlers.WatchedFileHandler
args = ('/var/log/api-localized.log',)
formatter = context

[handler_translator]
class = oslo_i18n.log.TranslationHandler
target = translatedlog
args = ('zh_CN',)

If the specified locale is not available in the system, the handler will log in the default locale.

emit(record)¶

Emit a record.

Append the record. If shouldFlush() tells us to, call flush() to process the buffer.

setFormatter(fmt)¶

Set the formatter for this handler.

oslo_i18n.fixture¶

Test fixtures for working with oslo_i18n.

class oslo_i18n.fixture.PrefixLazyTranslation(languages=None, locale=None)¶

Fixture to prefix lazy translation enabled messages

Use of this fixture will cause messages supporting lazy translation to be replaced with the message id prefixed with ‘domain/language:’. For example, ‘oslo/en_US: message about something’. It will also override the available languages returned from oslo_18n.get_available_languages to the specified languages.

This will enable tests to ensure that messages were translated lazily with the specified language and not immediately with the default language.

NOTE that this does not work unless lazy translation is enabled, so it uses the ToggleLazy fixture to enable lazy translation.

Parameters:	languages (list of strings) – list of languages to support. If not specified (None) then [‘en_US’] is used.

__init__(languages=None, locale=None)¶

Initialize self. See help(type(self)) for accurate signature.

setUp()¶

Prepare the Fixture for use.

This should not be overridden. Concrete fixtures should implement _setUp. Overriding of setUp is still supported, just not recommended.

After setUp has completed, the fixture will have one or more attributes which can be used (these depend totally on the concrete subclass).

Raises:	MultipleExceptions if _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception.
Returns:	None.
Changed in 1.3:	The recommendation to override setUp has been reversed - before 1.3, setUp() should be overridden, now it should not be.
Changed in 1.3.1:
	BaseException is now caught, and only subclasses of Exception are wrapped in MultipleExceptions.

class oslo_i18n.fixture.ToggleLazy(enabled)¶

Fixture to toggle lazy translation on or off for a test.

__init__(enabled)¶

Force lazy translation on or off.

Parameters:	enabled (bool) – Flag controlling whether to enable or disable lazy translation, passed to enable_lazy().

setUp()¶

Prepare the Fixture for use.

This should not be overridden. Concrete fixtures should implement _setUp. Overriding of setUp is still supported, just not recommended.

After setUp has completed, the fixture will have one or more attributes which can be used (these depend totally on the concrete subclass).

Raises:	MultipleExceptions if _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception.
Returns:	None.
Changed in 1.3:	The recommendation to override setUp has been reversed - before 1.3, setUp() should be overridden, now it should not be.
Changed in 1.3.1:
	BaseException is now caught, and only subclasses of Exception are wrapped in MultipleExceptions.

class oslo_i18n.fixture.Translation(domain='test-domain')¶

Fixture for managing translatable strings.

This class provides methods for creating translatable strings using both lazy translation and immediate translation. It can be used to generate the different types of messages returned from oslo_i18n to test code that may need to know about the type to handle them differently (for example, error handling in WSGI apps, or logging).

Use this class to generate messages instead of toggling the global lazy flag and using the regular translation factory.

__init__(domain='test-domain')¶

Initialize the fixture.

Parameters:	domain (str) – The translation domain. This is not expected to coincide with an actual set of message catalogs, but it can.

immediate(msg)¶

Return a string as though it had been translated immediately.

Parameters:	msg (str or unicode) – Input message string. May optionally include positional or named string interpolation markers.

lazy(msg)¶

Return a lazily translated message.

Parameters:	msg (str or unicode) – Input message string. May optionally include positional or named string interpolation markers.