{"id":8999,"library":"flufl-i18n","title":"flufl-i18n","description":"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.","status":"active","version":"6.0.0","language":"en","source_language":"en","source_url":"https://gitlab.com/warsaw/flufl.i18n","tags":["i18n","internationalization","localization","gettext","translation"],"install":[{"cmd":"pip install flufl-i18n","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"symbol":"initialize","correct":"from flufl.i18n import initialize"},{"symbol":"Application","correct":"from flufl.i18n import Application"},{"symbol":"RuntimeTranslator","correct":"from flufl.i18n import RuntimeTranslator"},{"symbol":"TranslationStrategy","correct":"from flufl.i18n import TranslationStrategy"},{"note":"The underscore function `_` is commonly bound after initialization, often from `Application.gettext` or `RuntimeTranslator.gettext`.","symbol":"_","correct":"_ = initialize('my_app_name', os.path.dirname(__file__)).gettext"}],"quickstart":{"code":"import os\nfrom flufl.i18n import initialize\n\n# --- Create a dummy messages.py for demonstration ---\n# In a real application, this would be a Python package\n# containing your compiled .mo files in subdirectories.\n# e.g., messages/en/LC_MESSAGES/my_app_name.mo\n#      messages/xx/LC_MESSAGES/my_app_name.mo (for our example 'xx')\n\n# Simulate a simple translation catalog (rot13 for 'xx' locale)\n# In a real scenario, this would involve gettext and .po/.mo files.\nclass MockTranslator:\n    def gettext(self, message):\n        if os.environ.get('LANG') == 'xx':\n            return message.encode('rot13').decode('utf-8')\n        return message\n\nclass MockApplication:\n    def __init__(self, name, localepath):\n        self.name = name\n        self.localepath = localepath\n\n    def gettext(self):\n        return MockTranslator()\n\n# Patch initialize for this example to use our mock app\n# In a real app, initialize() would handle catalog loading from LOCPATH\ndef _mock_initialize(app_name, package_path=None):\n    print(f\"Initializing i18n for app: {app_name}\")\n    print(f\"Using LOCPATH: {os.environ.get('LOCPATH')}\")\n    print(f\"Using LANG: {os.environ.get('LANG')}\")\n    return MockApplication(app_name, package_path)\n\nflufl.i18n.initialize = _mock_initialize\n# --- End of dummy setup ---\n\n\n# Example usage:\napp_name = 'my_app_name'\n\n# 1. Set up environment variables (typically done outside the script)\n#    For demonstration, we set them here.\n\n# IMPORTANT: Use os.path.dirname(__file__) to point to where your 'messages' package is\n# For this quickstart, we're simulating, so package_path isn't strictly used by our mock.\npackage_path = os.path.join(os.path.dirname(__file__), 'messages') # Placeholder\n\nos.environ['LANG'] = 'en' # Default language\nos.environ['LOCPATH'] = package_path # Path to your translation catalogs\n\n# Initialize the application and bind the translation function\n_ = initialize(app_name, package_path).gettext()\n\nprint(f\"English: {_('Hello, world!')}\")\nprint(f\"English: {_('How are you?')}\")\n\n# 2. Switch language context (e.g., for a web server or specific user session)\nos.environ['LANG'] = 'xx' # A faux language for demonstration\n\n# Re-initialize or push a new context (initialize here for simplicity in single-context example)\n_ = initialize(app_name, package_path).gettext()\n\nprint(f\"Faux (XX): {_('Hello, world!')}\")\nprint(f\"Faux (XX): {_('How are you?')}\")\n\n# Clean up environment variables (optional)\ndel os.environ['LANG']\ndel os.environ['LOCPATH']","lang":"python","description":"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."},"warnings":[{"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).","message":"Version 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.","severity":"breaking","affected_versions":">=6.0.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Historically, 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install flufl-i18n`.","cause":"The `flufl-i18n` package is not installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'flufl.i18n'"},{"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.","cause":"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.","error":"TypeError: 'NoneType' object is not callable"},{"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.","cause":"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.","error":"Translations are not applied; original strings are returned even after setup."}]}