Install & Compatibility
Where this runs
tested against v6.0.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.049s · 17.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.047s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
initialize
✓ from flufl.i18n import initialize
Application
✓ from flufl.i18n import Application
RuntimeTranslator
✓ from flufl.i18n import RuntimeTranslator
TranslationStrategy
✓ from flufl.i18n import TranslationStrategy
_
✓ _ = initialize('my_app_name', os.path.dirname(__file__)).gettext
The underscore function `_` is commonly bound after initialization, often from `Application.gettext` or `RuntimeTranslator.gettext`.
Demonstrates basic setup for a single-context application using `initialize()` and the `_()` translation function. It simulates setting environment variables (`LANG`, `LOCPATH`) and binding the translation function. For actual use, you would prepare `.po` and `.mo` files for your application.
import os
from flufl.i18n import initialize
# --- Create a dummy messages.py for demonstration ---
# In a real application, this would be a Python package
# containing your compiled .mo files in subdirectories.
# e.g., messages/en/LC_MESSAGES/my_app_name.mo
# messages/xx/LC_MESSAGES/my_app_name.mo (for our example 'xx')
# Simulate a simple translation catalog (rot13 for 'xx' locale)
# In a real scenario, this would involve gettext and .po/.mo files.
class MockTranslator:
def gettext(self, message):
if os.environ.get('LANG') == 'xx':
return message.encode('rot13').decode('utf-8')
return message
class MockApplication:
def __init__(self, name, localepath):
self.name = name
self.localepath = localepath
def gettext(self):
return MockTranslator()
# Patch initialize for this example to use our mock app
# In a real app, initialize() would handle catalog loading from LOCPATH
def _mock_initialize(app_name, package_path=None):
print(f"Initializing i18n for app: {app_name}")
print(f"Using LOCPATH: {os.environ.get('LOCPATH')}")
print(f"Using LANG: {os.environ.get('LANG')}")
return MockApplication(app_name, package_path)
flufl.i18n.initialize = _mock_initialize
# --- End of dummy setup ---
# Example usage:
app_name = 'my_app_name'
# 1. Set up environment variables (typically done outside the script)
# For demonstration, we set them here.
# IMPORTANT: Use os.path.dirname(__file__) to point to where your 'messages' package is
# For this quickstart, we're simulating, so package_path isn't strictly used by our mock.
package_path = os.path.join(os.path.dirname(__file__), 'messages') # Placeholder
os.environ['LANG'] = 'en' # Default language
os.environ['LOCPATH'] = package_path # Path to your translation catalogs
# Initialize the application and bind the translation function
_ = initialize(app_name, package_path).gettext()
print(f"English: {_('Hello, world!')}")
print(f"English: {_('How are you?')}")
# 2. Switch language context (e.g., for a web server or specific user session)
os.environ['LANG'] = 'xx' # A faux language for demonstration
# Re-initialize or push a new context (initialize here for simplicity in single-context example)
_ = initialize(app_name, package_path).gettext()
print(f"Faux (XX): {_('Hello, world!')}")
print(f"Faux (XX): {_('How are you?')}")
# Clean up environment variables (optional)
del os.environ['LANG']
del os.environ['LOCPATH']
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flufl.i18n'
The `flufl-i18n` package is not installed in the active Python environment.
fixInstall the package using pip: `pip install flufl-i18n`.
TypeError: 'NoneType' object is not callable
The translation function `_()` was called before `flufl.i18n.initialize()` or a similar setup function had properly bound a callable translator to it, or the bound function went out of scope.
fixEnsure `initialize()` is called once at application startup, and that the returned translation function (e.g., `_ = initialize(...).gettext()`) is accessible in the scope where translations are needed.
Translations are not applied; original strings are returned even after setup.
The translation catalogs (`.mo` files) are either missing, malformed, or the `LOCPATH` environment variable (or custom `TranslationStrategy` configuration) does not correctly point to the directory structure where the compiled message files are located. By default, `flufl.i18n` returns the original string if a translation is not found.
fixVerify that your `.mo` files are correctly compiled (e.g., using `msgfmt`) and placed in the expected directory structure: `LOCPATH/<language_code>/LC_MESSAGES/<application_name>.mo`. Ensure that `os.environ['LOCPATH']` is set to the parent directory containing these language directories, or configure a custom `TranslationStrategy` to locate them.
Upgrade
Version history
6.0.0latest on PyPI · released Nov 29, 2025
Audit
Dependencies
No dependency data recorded yet.