{"id":8118,"library":"django-statici18n","title":"Django Static i18n","description":"django-statici18n is a Django application designed to compile i18n JavaScript catalogs into static files. This addresses the performance overhead associated with Django's default dynamic `JSONCatalog` view, which generates JavaScript code on each request. The library is actively maintained and supports all officially supported Django versions, currently including 4.2 LTS, 5.2 LTS, and 6.0 series.","status":"active","version":"2.7.1","language":"en","source_language":"en","source_url":"https://github.com/zyegfryed/django-statici18n","tags":["Django","i18n","JavaScript","static files","internationalization","localization","performance"],"install":[{"cmd":"pip install django-statici18n","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core framework dependency, requires >=4.2,<6.1","package":"Django","optional":false},{"reason":"Used for managing application settings, requires >=1.0","package":"django-appconf","optional":false},{"reason":"Required by Django's i18n machinery for message compilation (system-level dependency usually)","package":"gettext","optional":false}],"imports":[{"note":"Used in Django templates to load the provided template tags.","symbol":"statici18n","correct":"{% load statici18n %}"},{"note":"This is a Django management command, not a Python import. It's run from the command line.","symbol":"compilejsi18n","correct":"python manage.py compilejsi18n"}],"quickstart":{"code":"import os\n\n# settings.py\n# ...\n\nINSTALLED_APPS = [\n    # ...\n    'django.contrib.staticfiles',\n    'statici18n',\n]\n\nTEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [],\n        'APP_DIRS': True,\n        'OPTIONS': {\n            'context_processors': [\n                # ...\n                'django.template.context_processors.i18n',\n            ],\n        },\n    },\n]\n\n# Define LOCALE_PATHS to ensure Django finds your translation files\nLOCALE_PATHS = [\n    os.path.join(BASE_DIR, 'locale'),\n]\n\n# Optional: Configure output directory if different from default (STATIC_ROOT/jsi18n)\n# STATICI18N_ROOT = os.path.join(BASE_DIR, 'static_i18n_output')\n# STATICI18N_OUTPUT_DIR = 'js_catalogs'\n\n# project/templates/base.html (or any template where JS i18n is needed)\n# ...\n# {% load static i18n %}\n# {% load statici18n %}\n# <script src=\"{% statici18n LANGUAGE_CODE %}\"></script>\n# ...\n\n# After making changes to messages:\n# python manage.py makemessages -l en\n# python manage.py compilemessages\n# python manage.py compilejsi18n\n# python manage.py collectstatic\n","lang":"python","description":"To quickly set up `django-statici18n`:\n1. Add `statici18n` and `django.contrib.staticfiles` to `INSTALLED_APPS`.\n2. Ensure `django.template.context_processors.i18n` is in your `TEMPLATES` context processors.\n3. Define `LOCALE_PATHS` in your settings to point to your translation directories.\n4. Run `python manage.py makemessages`, then `python manage.py compilemessages` to create and compile your translation files.\n5. Execute `python manage.py compilejsi18n` to generate the static JavaScript catalogs.\n6. Include the generated script in your templates using `{% load statici18n %}` and `{% statici18n LANGUAGE_CODE %}`."},"warnings":[{"fix":"Implement `django-statici18n` as described in the quickstart to generate and serve static JavaScript catalogs.","message":"Dynamic `JSONCatalog` view performance overhead: Django's default `JSONCatalog` view generates JavaScript catalogs dynamically on each request, which can introduce significant overhead as your site scales. `django-statici18n` solves this by pre-compiling these catalogs into static files.","severity":"gotcha","affected_versions":"All Django versions using `JSONCatalog` without static compilation."},{"fix":"Ensure your Django project is running a version compatible with `django-statici18n` (currently >=4.2) and that no custom code relies on the deprecated `mimetype` argument for `JavaScriptCatalog`.","message":"Django's `JavaScriptCatalog` view, a core component, no longer accepts `mimetype` argument in Django 1.6+. It's been renamed to `content_type`. While `django-statici18n` abstracts this, be aware of underlying Django changes if debugging.","severity":"breaking","affected_versions":"Django < 1.6"},{"fix":"Verify that `LOCALE_PATHS` is correctly configured in your `settings.py` to point to the directories containing your `locale` folders. Also, ensure `makemessages` and `compilemessages` were run successfully.","message":"Empty or missing JavaScript catalogs after running `compilejsi18n`. This usually indicates that Django cannot find your locale paths or translation files.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `django.contrib.staticfiles` is in `INSTALLED_APPS`, `STATIC_URL` and `STATIC_ROOT` are properly defined, and you are running `collectstatic` in production. For development, ensure `DEBUG = True` and `STATIC_URL` is configured, or explicitly serve static files.","message":"Static files (including i18n catalogs) not served in development or production. `django-statici18n` relies on Django's static files infrastructure.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `LOCALE_PATHS = [os.path.join(BASE_DIR, 'locale')]` to your `settings.py` (adjust path as needed). Run `python manage.py makemessages -l <your_locale>` followed by `python manage.py compilemessages`.","cause":"Django cannot locate your translation files. This often means `LOCALE_PATHS` is not set or is incorrect, or `makemessages` hasn't been run.","error":"CommandError: Unable to find locale data for domain 'djangojs' in path(s) ..."},{"fix":"Add `'statici18n'` to `INSTALLED_APPS` in `settings.py`. In your Django template, ensure `{% load statici18n %}` is present at the top before using `{% statici18n %}` or `{% inlinei18n %}`.","cause":"The `statici18n` app is either not in `INSTALLED_APPS` or the template tag `{% load statici18n %}` is missing in your template.","error":"'statici18n' is not a registered tag library"},{"fix":"Ensure you have `{% load statici18n %}` and `<script src=\"{% statici18n LANGUAGE_CODE %}\"></script>` in your HTML *before* any other scripts that try to use `gettext`. Also, run `python manage.py compilejsi18n`.","cause":"The static JavaScript i18n catalog, which provides the `gettext` function, has not been loaded in your HTML, or `compilejsi18n` was not run.","error":"ReferenceError: gettext is not defined"},{"fix":"1. Run `python manage.py makemessages` and `python manage.py compilemessages` to ensure `.mo` files are up-to-date. 2. Verify `STATICI18N_PACKAGES` (default: `('django.conf')`) includes your app(s) that contain `locale` directories. 3. Clear your browser cache or use cache-busting techniques (e.g., Django's `CachedStaticFilesStorage`).","cause":"Either the translation files (`.po`, `.mo`) are outdated or incorrect, the `STATICI18N_PACKAGES` setting is not including the app with the translations, or the browser cache is serving an old version.","error":"Translations are not appearing in JavaScript despite `compilejsi18n` being run."}]}