Install & Compatibility
Where this runs
tested against v6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.141s · 29.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.0s · import 0.131s · 30MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
translate
✓ from zope.i18n import translate
The primary function for manual translation of Message objects or strings.
MessageFactory
✓ from zope.i18nmessageid import MessageFactory
Used to create a factory for message IDs tied to a specific translation domain, often aliased as '_'.
getRequest
✓ from zope.globalrequest import getRequest
Retrieves the current HTTP request object, which is crucial for determining the target language in a web context.
This quickstart demonstrates how to define a translatable message using `MessageFactory` (commonly aliased as `_`) and then translate it using the `translate` function. It includes a minimal mock for the request context, which is typically provided by the Zope application server for language negotiation. It also hints at the environment variable for automatic MO file compilation.
import os
from zope.i18n import translate
from zope.i18nmessageid import MessageFactory
# Simulate a request object for translation context
class MockRequest:
def __init__(self, lang):
self.LANGUAGE_NEGOTIATED = lang
self.locale = MockLocale(lang)
class MockLocale:
def __init__(self, lang):
self.getLocaleID = lambda: lang
# Define a message factory for your domain
_ = MessageFactory('my.application')
# A translatable message
msg = _('hello_world_id', default='Hello, World!', mapping={'name': 'User'})
# Example of a simple translation service (in a real Zope app, this would be set up)
def get_translation_service(request):
# In a real Zope setup, this would resolve the utility
# For this example, we just return the 'translate' function itself
return lambda message, target_language=None, default=None, mapping=None, context=None, domain=None:
if target_language == 'de':
return f"Hallo, {mapping.get('name', '')}!"
elif target_language == 'fr':
return f"Bonjour, {mapping.get('name', '')}!"
return default if default else str(message) # Fallback
# Translate the message
# Often, the request context implicitly provides the target_language
mock_request_en = MockRequest('en')
mock_request_de = MockRequest('de')
mock_request_fr = MockRequest('fr')
# Using translate with a mocked context and explicit target language
translated_en = translate(msg, target_language='en', context=mock_request_en, mapping={'name': 'Alice'})
translated_de = translate(msg, target_language='de', context=mock_request_de, mapping={'name': 'Bob'})
translated_fr = translate(msg, target_language='fr', context=mock_request_fr, mapping={'name': 'Charlie'})
print(f"English: {translated_en}")
print(f"German: {translated_de}")
print(f"French: {translated_fr}")
# Example for automatic MO file compilation (if 'compile' extra is installed)
os.environ['ZOPE_I18N_COMPILE_MO_FILES'] = 'true'
# In a real application, MO files would now be compiled on startup if .po files exist
print(f"\nZOPE_I18N_COMPILE_MO_FILES env var set: {os.environ.get('ZOPE_I18N_COMPILE_MO_FILES')}")
Errors
Common errors & fixes
NameError: global name '_' is not defined
Attempting to use the `_` (MessageFactory) function in a Zope Restricted Python script without explicitly importing it or declaring it public.
fixIn your `__init__.py` (or similar product setup), declare `YourDomainMessageFactory = MessageFactory('your.domain')` and make it public using `ModuleSecurityInfo('your.packagename').declarePublic('YourDomainMessageFactory')`. Then import it as `from your.packagename import YourDomainMessageFactory as _` in your Restricted Python scripts. Numbers or dates are formatted incorrectly (e.g., '2.021' instead of '2021' for a year in German).
Default locale formatters in `zope.i18n.locales` provide specific number/date patterns that might not align with desired display formats, especially for region-specific nuances.
fixOverride the default locale definitions. This typically involves copying the relevant XML locale file (e.g., `de.xml`) from `zope.i18n.locales.data` into your project's locale directory and modifying the `<numbers>` or `<dates>` section as needed.
Translated text overflows UI elements or breaks layout.
Different languages have varying text lengths (e.g., German words are often longer than English), leading to UI elements not accommodating translated strings.
fixDesign UI elements with flexibility in mind (e.g., using dynamic sizing, Flexbox, CSS Grid) rather than fixed widths. Provide ample padding and margins. Thorough localization testing is essential to catch these issues early.
Upgrade
Version history
6.0latest on PyPI · released Sep 12, 2025
Audit
Dependencies
zope.i18nmessageidrequiredUsed for declaring translatable message IDs with domain information.
zope.globalrequestoptionalOften needed to provide a request object for the translate function, especially in a Zope/Plone context.
gettextoptionalUnderlying library for message catalog handling. Required if compiling .po files.