FAQ

How to configure static files with django-statici18n?

Due to the modularity of django.contrib.staticfiles it’s easy to use the storage facility provided by tweaking some settings.

There’s two solution leveraging the STATICFILES_FINDERS setting:

  • using a dedicated application, or,
  • using a dedicated directory to hold the catalog files.

In the next sections, we’ll detail with examples how to use both solutions. Choose the one that best fits your needs and/or taste.

See static files management for more information.

Once setup is in place, run the compilejsi18n command to compile/update the Javascript catalog files followed by the collectstatic command to generate the static files:

# compile/update Javascript catalog files...
$ python manage.py compilejsi18n

# then, collect static files.
$ python manage.py collectstatic

Using a placeholder app

You need to have the AppDirectoriesFinder finder enabled (the default).

Create a minimal app with a static subdirectory. For example, let’s create an app named ì18n to hold the generated catalogs:

cd /path/to/your/django/project
mkdir -p i18n/static
touch i18n/__init__.py i18n/models.py

Your project layout should then looks like the following:

example_project
|-- app
|   |-- __init__.py
|   |-- admin.py
|   |-- locale
|   |-- models.py
|   |-- static
|   |-- templates
|   |-- tests.py
|   `-- views.py
|-- i18n                   <-- Your dedicated app
|   |-- __init__.py
|   |-- models.py          <-- A placeholder file to enable app loading
|   `-- static             <-- The output directory of catalog files
|       `-- jsi18n
|-- manage.py
|-- project
|   |-- __init__.py
|   |-- locale
|   |-- settings.py
|   |-- templates
|   `-- urls.py
`-- public
    `-- static             <-- The output directory of collected
        `-- jsi18n             static files for deployment

Then update your settings accordingly. Following the previous example:

# project/settings.py

# ... the rest of your settings here ...

INSTALLED_APPS = (
    'django.contrib.staticfiles',
    # ...
    'statici18n',
    'i18n',
)

STATIC_ROOT = os.path.join(BASE_DIR, "public", "static")
STATICI18N_ROOT = os.path.join(BASE_DIR, "i18n", "static")

Using a placeholder directory

This approach extends the STATICFILES_DIRS setting. You need to have the FileSystemFinder finder enabled (the default).

Following is an example project layout:

example_project
|-- app
|   |-- __init__.py
|   |-- admin.py
|   |-- locale
|   |-- models.py
|   |-- tests.py
|   `-- views.py
|-- manage.py
|-- project
|   |-- __init__.py
|   |-- locale
|   |-- settings.py
|   |-- static             <-- Directory holding catalog files
|   |   `-- jsi18n
|   |-- templates
|   `-- urls.py
`-- public
    `-- static             <-- The output directory of collected
                               static files for deployment

Then update your settings accordingly. Following the previous example:

# project/settings.py

# ... the rest of your settings here ...

INSTALLED_APPS = (
    'django.contrib.staticfiles',
    # ...
    'statici18n',
)

STATIC_ROOT = os.path.join(BASE_DIR, "public", "static")
STATICI18N_ROOT = os.path.join(BASE_DIR, "project", "static")
STATICFILES_DIRS += (STATICI18N_ROOT,)

Can I use the generated catalog with RequireJS?

Yes. You just need some boilerplate configuration to export the object reference, like the following:

# settings.py
STATICI18N_ROOT = os.path.join(BASE_DIR, "project", "static")
STATICFILES_DIRS += (STATICI18N_ROOT,)

# app.js
require.config({
        baseUrl: "static/js",
        paths: {
                "jsi18n": "../jsi18n/{{ LANGUAGE_CODE }}/djangojs",
        },
        shim: {
                "jsi18n":
                {
                        exports: 'django'
                },
        }
}

// Usage
require(["jquery", "jsi18n"], function($, jsi18n) {
    console.log(jsi18n.gettext('Internationalization is fun !'));
        // > "L’internationalisation, c'est cool !"
}