django-lang

GitHub

Test

Check Demo Project

• Check the demo repo on GitHub

Requirements

• Python 3.9+ supported.
• Django 3.2+ supported.

Setup

1. Install from pip:

   pip install django-lang
   

2. Modify settings.py by adding the app to INSTALLED_APPS:

   INSTALLED_APPS = [
       # ...
       "lang",
       # ...
   ]
   

3. Modify settings.py by adding the app to INSTALLED_APPS:

   TEMPLATES = [
       {
           "BACKEND": "django.template.backends.django.DjangoTemplates",
           "DIRS": [os.path.join(PROJECT_DIR, "templates")],
           "APP_DIRS": True,
           "OPTIONS": {
               "context_processors": [
                   "django.template.context_processors.debug",
                   "django.template.context_processors.request",
                   "django.contrib.auth.context_processors.auth",
                   "django.contrib.messages.context_processors.messages",
                   "lang.context_processors.from_settings",
                   "lang.context_processors.seo_i18n",
               ],
           },
       },
   ]
   

   Optional: lang.context_processors.language_switcher_next (fills redirect_to for the packaged language form).

Optional: SetLanguageNextPathMiddleware

Only needed if you use translated URL segments (gettext_lazy under i18n_patterns) and see language switches that POST to set_language but stay on the wrong prefix. Short how-to: docs/set_language_middleware.md.

4. Modify your project's base template base.html to include language's switcher styles:

   <head>
       ...
       <link rel="stylesheet" type="text/css" href="{% static 'lang/css/nav-link.css' %}">
       ...
   </head>
   

5. Modify your project's base template base.html to include attributes using translate_url template's tag:

   <head>
       ...
       <meta name="language" content="{{ LANGUAGE_CODE }}" />
       {% include "hreflang.html" %}
       ...
   </head>
   

6. Modify your project's nav template nav.html to include language's switcher:

   <nav class="navbar">
       ...
       <ul class="nav navbar-nav">
           {% include "lang/nav-link.html" %}
       </ul>
       ...
   </nav>
   

Configuration: lang.conf and APP_CONFIG

Built-in maps live in lang.defaults. At runtime, :mod:lang.conf resolves values lazily:

1. Top-level Django settings (LANGUAGE_HREFLANG_MAP, LANGUAGE_WIKIPEDIA_SAMEAS, OG_LOCALE_BY_LANGUAGE, HREFLANG_DEFAULT_LANGUAGE, LANGUAGE_FLAG_MAP), if set.
2. Partial dicts under settings.APP_CONFIG["lang"] merged onto the package defaults (for the three LANGUAGE_* / OG_* maps and flag overrides).
3. Otherwise the content of lang.defaults.

You do not need to import lang.defaults from settings.py. Typical site-only override for x-default::

APP_CONFIG = {
    "lang": {
        "HREFLANG_DEFAULT_LANGUAGE": "it",
    },
}

Or use the usual flat settings (full replacement for the dict keys, or HREFLANG_DEFAULT_LANGUAGE at top level) if you prefer.

Optional: language control beside the hamburger on small viewports

nav-link-standalone.css shows the extra switcher next to the menu toggle below the lg breakpoint (~992px) and hides the duplicate inside the collapsed drawer. Optional script display-standalone-class.js only adds class display-standalone on <html> for installed web apps; layout no longer depends on it.

1. In settings.py, add the optional context processor so redirect_to is filled for set_language’s next (unless you pass redirect_to from each view):

   "lang.context_processors.language_switcher_next",
   

2. In the base layout <head>, after nav-link.css, add:

   <link rel="stylesheet" href="{% static 'lang/css/nav-link-standalone.css' %}">
   <script src="{% static 'lang/js/display-standalone-class.js' %}"></script>
   

3. Next to your mobile menu button, include:

   {% include "lang/nav-link-standalone.html" %}
   

Packaged templates:

• hreflang.html (app template root) — <link rel="alternate" hreflang="…"> for the current view.
• lang/nav-link.html — language <select> (optional context: lang_switcher_id, lang_switcher_extra_class).
• lang/nav-link-standalone.html — duplicate switcher beside the mobile toggle (small viewports / PWA).

Run Example Project

git clone --depth=50 --branch=django-lang https://github.com/DLRSP/example.git DLRSP/example
cd DLRSP/example
python manage.py runserver

Now browser the app @ http://127.0.0.1:8000

References

• brainstorm.it - Language's switching
• hakibenita.com - Url's translation for "hreflang" html's attributes