django-sage-language 0.1.2

A Django Project for changing language.

Sage Language Middleware for Django

This Django project provides middleware and utility classes to support multilingual applications through URL prefixes and cookies for language settings. The core feature is a custom CookieLocaleMiddleware, which dynamically manages user language preferences and redirects users to the appropriate language version of the site based on URL paths or cookies.

Features

• Dynamic Language Detection: Determines the preferred language by examining URL prefixes and cookies.
• Custom Middleware: CookieLocaleMiddleware extends Django's default LocaleMiddleware, enhancing support for multilingual content.
• URL Prefix Management: Utilities to add or remove language prefixes in URLs, supporting a clean and consistent URL structure.
• Customizable Language Settings: Integrates with Django's internationalization settings (LANGUAGES, LANGUAGE_CODE, etc.) for easy customization.
• Error Checking: Ensures proper configuration of language settings and middleware placement.

Project Structure

• middlewares/cookie.py: Contains CookieLocaleMiddleware to manage language preferences dynamically.
• utils/locale.py: Provides MultilingualService, a utility class for adding and removing language prefixes in URLs.
• views/locale.py: Implements SetLanguageView, allowing users to set their preferred language through a POST request.
• checks.py: Validates the configuration of middleware, language settings, and cookies.
• settings.py: Configures Django's settings, including LANGUAGES, LANGUAGE_CODE, and middleware setup.
• urls.py: Configures routes for language switching and i18n patterns.

Installation

Using pip

1. Create a Virtual Environment:

   python -m venv .venv
   

2. Activate the Virtual Environment:

   • On Windows:

     .venv\Scripts\activate
     

   • On macOS and Linux:

     source .venv/bin/activate
     

3. Install the Package:

   pip install python-sage-bbb
   

Using Poetry

1. Install Poetry: Follow the official installation instructions at the Poetry website.

2. Create a New Project (Optional):

   poetry new myproject
   cd myproject
   

3. Add the Package as a Dependency:

   poetry add python-sage-bbb
   

4. Activate the Virtual Environment:

   poetry shell
   

Configuration

1. Add sage_language to INSTALLED_APPS in settings.py:

   INSTALLED_APPS = [
       ...
       'sage_language',
   ]
   

2. Middleware Configuration: Ensure CookieLocaleMiddleware is added immediately after SessionMiddleware in the MIDDLEWARE setting:

   MIDDLEWARE = [
       'django.middleware.security.SecurityMiddleware',
       'django.contrib.sessions.middleware.SessionMiddleware',
       'sage_language.middlewares.cookie.CookieLocaleMiddleware',
       ...
   ]
   

3. Set Language Settings: Define supported languages, default language, and cookie names:

   LANGUAGES = [
       ('en', 'English'),
       ('fa', 'Farsi'),
       ('es', 'Spanish'),
   ]
   LANGUAGE_CODE = 'en'
   SAGE_LANGUAGE_COOKIE_NAME = "ivan_language"
   LANGUAGE_COOKIE_NAME = SAGE_LANGUAGE_COOKIE_NAME
   

4. Add URL Configuration for Language Switching: In urls.py, set up the language switching view:

   from sage_language.views import SetLanguageView
   urlpatterns = [
       path('set-language/', SetLanguageView.as_view(), name='set_language'),
       path("i18n/", include("django.conf.urls.i18n")),
   ]
   

Usage

1. Setting Language Preference: To change the language preference, make a POST request to /set-language/ with language and next parameters:

   • language: The desired language code (e.g., 'en', 'fa', 'es').
   • next: The URL to redirect to after setting the language.

2. URL Prefix Management: The middleware automatically adds or removes language prefixes from URLs based on the user’s selected language and cookie settings.

3. Automatic Language Redirection: If a user’s preferred language (stored in a cookie) differs from the language in the URL, the middleware will redirect them to the correct URL.

Notes

• Make sure to set USE_I18N, USE_L10N, and USE_TZ to True in settings.py for proper internationalization support.
• For production use, ensure SAGE_LANGUAGE_COOKIE_NAME and LANGUAGE_COOKIE_NAME are set to the same value for consistent cookie management.