Registry / flufl-i18n

flufl-i18n

JSON →
library6.0.0pypypi✓ verified 86d ago

flufl.i18n is a Python library providing a high-level, convenient API for managing internationalization (i18n) translation contexts. It supports both single-context applications like command-line tools and more complex, multi-context applications such as servers. The current version is 6.0.0, released in November 2025, with a consistent release cadence for updates and Python version compatibility.

pip install flufl-i18n
INSTALL
IMPORT
SIG · FLUFL-I18N
F
flufl-i18n
pythonv6.0.0
Install
1.6s avg
Import
48ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.049s · 17.9MB
glibc
py 3.103.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']
Debug
Known issues
breakingVersion 6.0.0 of `flufl.i18n` requires Python 3.10 or newer. Support for Python 3.9 and earlier versions has been dropped. Ensure your environment meets the minimum Python version requirement before upgrading.
fix
Upgrade to Python 3.10 or newer, or pin `flufl-i18n` to an older compatible version (e.g., `flufl-i18n<6.0.0` for Python 3.9).
affects: >=6.0.0
gotchaThe `initialize()` function and `SimpleStrategy` by default heavily rely on the `$LANG` and `$LOCPATH` environment variables for discovering translation catalogs. If these variables are not set, or you require dynamic language switching not based on environment variables (e.g., per-request in a web app), you'll need to use the more flexible `Application` and `RuntimeTranslator` APIs with custom `TranslationStrategy` implementations.
fix
For simple cases, ensure `LANG` and `LOCPATH` are correctly set in your environment. For complex scenarios, use `flufl.i18n.Application` and explicitly register `TranslationStrategy` instances, then manage contexts with `Application.push()`/`pop()` or `RuntimeTranslator`.
affects: All
gotchaHistorically, there have been inconsistencies in how package names with dots (e.g., `flufl.i18n`) versus hyphens (`flufl-i18n`) are handled by PyPI and wheel specifications, affecting packaging tools. This could lead to issues during build or upload with certain older or non-standard build backends.
fix
Always install using `pip install flufl-i18n` (using the hyphenated PyPI name). When packaging, ensure your build system correctly normalizes the package name for wheel filenames and metadata according to current PEP standards. Consult your build tool's documentation for specific configurations.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flufl.i18n'
The `flufl-i18n` package is not installed in the active Python environment.
fix
Install 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.
fix
Ensure `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.
fix
Verify 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.

Agent activity
4 hits · last 30 days
node
4
Resources
flufl-i18n — pip install flufl-i18n · libregistry