Django Static i18n

Common errors

• CommandError: Unable to find locale data for domain 'djangojs' in path(s) ...

  cause Django cannot locate your translation files. This often means `LOCALE_PATHS` is not set or is incorrect, or `makemessages` hasn't been run.
  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`.

• 'statici18n' is not a registered tag library

  cause The `statici18n` app is either not in `INSTALLED_APPS` or the template tag `{% load statici18n %}` is missing in your template.
  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 %}`.

• ReferenceError: gettext is not defined

  cause The static JavaScript i18n catalog, which provides the `gettext` function, has not been loaded in your HTML, or `compilejsi18n` was not run.
  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`.

• Translations are not appearing in JavaScript despite `compilejsi18n` being run.

  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.
  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`).

Warnings

• gotcha 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.
  Fix: Implement `django-statici18n` as described in the quickstart to generate and serve static JavaScript catalogs.
• breaking 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.
  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`.
• gotcha Empty or missing JavaScript catalogs after running `compilejsi18n`. This usually indicates that Django cannot find your locale paths or translation files.
  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.
• gotcha Static files (including i18n catalogs) not served in development or production. `django-statici18n` relies on Django's static files infrastructure.
  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.

Install

• pip install django-statici18n Install via pip

Imports

• statici18n

  {% load statici18n %}

  Used in Django templates to load the provided template tags.
• compilejsi18n

  python manage.py compilejsi18n

  This is a Django management command, not a Python import. It's run from the command line.

Quickstart

To quickly set up `django-statici18n`: 1. Add `statici18n` and `django.contrib.staticfiles` to `INSTALLED_APPS`. 2. Ensure `django.template.context_processors.i18n` is in your `TEMPLATES` context processors. 3. Define `LOCALE_PATHS` in your settings to point to your translation directories. 4. Run `python manage.py makemessages`, then `python manage.py compilemessages` to create and compile your translation files. 5. Execute `python manage.py compilejsi18n` to generate the static JavaScript catalogs. 6. Include the generated script in your templates using `{% load statici18n %}` and `{% statici18n LANGUAGE_CODE %}`.

import os

# settings.py
# ...

INSTALLED_APPS = [
    # ...
    'django.contrib.staticfiles',
    'statici18n',
]

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                # ...
                'django.template.context_processors.i18n',
            ],
        },
    },
]

# Define LOCALE_PATHS to ensure Django finds your translation files
LOCALE_PATHS = [
    os.path.join(BASE_DIR, 'locale'),
]

# Optional: Configure output directory if different from default (STATIC_ROOT/jsi18n)
# STATICI18N_ROOT = os.path.join(BASE_DIR, 'static_i18n_output')
# STATICI18N_OUTPUT_DIR = 'js_catalogs'

# project/templates/base.html (or any template where JS i18n is needed)
# ...
# {% load static i18n %}
# {% load statici18n %}
# <script src="{% statici18n LANGUAGE_CODE %}"></script>
# ...

# After making changes to messages:
# python manage.py makemessages -l en
# python manage.py compilemessages
# python manage.py compilejsi18n
# python manage.py collectstatic