Message Identifiers for internationalization

8.2 · active · verified Wed Apr 15

zope.i18nmessageid is a Python library, currently at version 8.2, that provides facilities for declaring translatable message identifiers within program source text. These message IDs encapsulate the untranslated string, a translation domain, and optional default values or substitutions. While this package handles the *declaration* of messages, their actual *translation* is the responsibility of the complementary zope.i18n package. It is actively maintained by the Zope Foundation.

Warnings

deprecated The `MessageID` and `MessageIDFactory` APIs from `zope.i18nmessageid.messageid` were deprecated in favor of `Message` and `MessageFactory` (imported directly from `zope.i18nmessageid` or `zope.i18nmessageid.message`).
Fix: Update imports to use `from zope.i18nmessageid import MessageFactory` and directly create `Message` objects if needed, or rely on the factory to create them.
gotcha This package only provides facilities for *declaring* message identifiers. It does not perform the actual translation of these messages into different languages. For translation, the `zope.i18n` package must be used in conjunction with message catalogs (e.g., PO/MO files).
Fix: Ensure `zope.i18n` is installed and properly configured if runtime translation is desired. Understand that `zope.i18nmessageid` primarily serves as a way to mark and carry translatable strings with their context.
gotcha When passing a `Message` object to `zope.i18n.translate` (the separate translation utility) along with an explicit `mapping` argument, the `mapping` provided directly to `translate` might override or not correctly merge with the mapping already present in the `Message` object, potentially leading to lost substitutions.
Fix: If dynamic substitutions are needed, ensure the `Message` object is created with the *complete* desired `mapping` from the start, or create a new `Message` object with the combined mapping before passing it to `translate`. Directly passing `unicode(X)` to `translate` will lose domain and default message information.

Install

pip install zope.i18nmessageid Install stable version

Imports

MessageFactory
wrong:
```
from zope.i18nmessageid.messageid import MessageIDFactory
```
correct:
```
from zope.i18nmessageid import MessageFactory
```
The MessageIDFactory and MessageID APIs were deprecated in favor of MessageFactory and Message (from zope.i18nmessageid.message) in zope.i18nmessageid 3.2.0 (released 2006).
Message
wrong:
```
from zope.i18nmessageid.messageid import MessageID
```
correct:
```
from zope.i18nmessageid.message import Message
```
The MessageIDFactory and MessageID APIs were deprecated in favor of MessageFactory and Message (from zope.i18nmessageid.message) in zope.i18nmessageid 3.2.0 (released 2006).

Quickstart

To use zope.i18nmessageid, you typically import `MessageFactory`, create an instance bound to your application's translation domain, and then use this factory to mark strings for translation. The resulting objects are `Message` instances, which carry the original string, domain, and any substitution mappings. Actual translation into a target language requires the `zope.i18n` package.

from zope.i18nmessageid import MessageFactory

# Define a message factory for your application's domain
# This is conventionally named '_' in many i18n contexts.
_ = MessageFactory('my.application.domain')

# Create a translatable message ID
greeting_msg = _('Hello, world!')
print(f"Raw Message ID: {greeting_msg!r}")
# Expected output for MessageID: <MessageID u'Hello, world!' domain='my.application.domain'>

# Message IDs can include variables for substitution
variable_msg = _('Welcome, ${name}!', mapping={'name': 'User'})
print(f"Raw Message ID with mapping: {variable_msg!r}")
# Expected output: <MessageID u'Welcome, ${name}!' domain='my.application.domain' mapping={'name': 'User'}>

view raw JSON →