{"id":6952,"library":"zope-i18nmessageid","title":"Message Identifiers for internationalization","description":"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.","status":"active","version":"8.2","language":"en","source_language":"en","source_url":"https://github.com/zopefoundation/zope.i18nmessageid","tags":["zope","i18n","internationalization","localization","message factory"],"install":[{"cmd":"pip install zope.i18nmessageid","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This package declares message IDs; zope.i18n is required for performing actual translations.","package":"zope.i18n","optional":true}],"imports":[{"note":"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).","wrong":"from zope.i18nmessageid.messageid import MessageIDFactory","symbol":"MessageFactory","correct":"from zope.i18nmessageid import MessageFactory"},{"note":"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).","wrong":"from zope.i18nmessageid.messageid import MessageID","symbol":"Message","correct":"from zope.i18nmessageid.message import Message"}],"quickstart":{"code":"from zope.i18nmessageid import MessageFactory\n\n# Define a message factory for your application's domain\n# This is conventionally named '_' in many i18n contexts.\n_ = MessageFactory('my.application.domain')\n\n# Create a translatable message ID\ngreeting_msg = _('Hello, world!')\nprint(f\"Raw Message ID: {greeting_msg!r}\")\n# Expected output for MessageID: <MessageID u'Hello, world!' domain='my.application.domain'>\n\n# Message IDs can include variables for substitution\nvariable_msg = _('Welcome, ${name}!', mapping={'name': 'User'})\nprint(f\"Raw Message ID with mapping: {variable_msg!r}\")\n# Expected output: <MessageID u'Welcome, ${name}!' domain='my.application.domain' mapping={'name': 'User'}>","lang":"python","description":"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."},"warnings":[{"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.","message":"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`).","severity":"deprecated","affected_versions":"< 3.2.0 (deprecated in 3.2.0, released 2006)"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Potentially all versions when interacting with `zope.i18n.translate`"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}