Django Internationalization: Building Multi-Language Applications

# Django 6.0 Internationalization Configuration

# settings.py
from django.utils.translation import gettext_lazy as _

# Enable internationalization
USE_I18N = True

# Enable localization (number and date formatting)
USE_L10N = True

# Enable timezone support
USE_TZ = True

# Default language
LANGUAGE_CODE = 'en-us'

# Available languages
LANGUAGES = [
    ('en', _('English')),
    ('es', _('Spanish')),
    ('fr', _('French')),
    ('de', _('German')),
    ('ja', _('Japanese')),
    ('zh-hans', _('Simplified Chinese')),
    ('ar', _('Arabic')),
]

# Locale paths (where translation files are stored)
import os
LOCALE_PATHS = [
    os.path.join(BASE_DIR, 'locale'),
]

# Middleware configuration
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.locale.LocaleMiddleware',  # After SessionMiddleware
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

# Timezone configuration
TIME_ZONE = 'UTC'

# Supported timezones for users
USER_TIMEZONES = [
    'UTC',
    'America/New_York',
    'America/Los_Angeles',
    'Europe/London',
    'Europe/Paris',
    'Asia/Tokyo',
    'Asia/Shanghai',
    'Australia/Sydney',
]

# Number and date formatting
USE_THOUSAND_SEPARATOR = True
THOUSAND_SEPARATOR = ','
DECIMAL_SEPARATOR = '.'

# Date and time formats
DATE_FORMAT = 'N j, Y'
SHORT_DATE_FORMAT = 'm/d/Y'
DATETIME_FORMAT = 'N j, Y, P'
TIME_FORMAT = 'P'

# Create locale directory structure
mkdir -p locale

# Project structure:
# myproject/
# ├── manage.py
# ├── myproject/
# │   ├── settings.py
# │   └── urls.py
# ├── myapp/
# │   ├── views.py
# │   ├── templates/
# │   └── locale/
# └── locale/  # Project-wide translations
#     ├── es/
#     │   └── LC_MESSAGES/
#     │       ├── django.po
#     │       └── django.mo
#     ├── fr/
#     └── de/

# Marking strings for translation in Python code

# In views and models - use gettext_lazy for translated strings
from django.utils.translation import gettext_lazy as _
from django.utils.translation import gettext, ngettext
from django.http import HttpResponse

def my_view(request):
    # Simple translation
    output = _("Welcome to our website")
    return HttpResponse(output)

# String interpolation with translation
def greeting_view(request):
    name = request.user.username
    # Use named placeholders
    message = _("Hello, %(name)s! Welcome back.") % {'name': name}
    return HttpResponse(message)

# Plural forms
def item_count_view(request, count):
    # ngettext handles plural forms automatically
    message = ngettext(
        'You have %(count)d item',
        'You have %(count)d items',
        count
    ) % {'count': count}
    return HttpResponse(message)

# Context-specific translations
from django.utils.translation import pgettext

def month_name(request):
    # 'month name' provides context for 'May' (month vs permission)
    may = pgettext('month name', 'May')
    # 'verb' provides different context
    may_verb = pgettext('verb', 'May')
    return HttpResponse(f"{may} vs {may_verb}")

# Model translations
from django.db import models
from django.utils.translation import gettext_lazy as _

class Article(models.Model):
    title = models.CharField(
        _('title'),
        max_length=200,
        help_text=_('Enter article title')
    )
    content = models.TextField(_('content'))
    
    class Meta:
        verbose_name = _('article')
        verbose_name_plural = _('articles')
    
    def __str__(self):
        return self.title

# Form translations
from django import forms

class ContactForm(forms.Form):
    name = forms.CharField(
        label=_('Your name'),
        help_text=_('Enter your full name')
    )
    email = forms.EmailField(
        label=_('Email address')
    )
    message = forms.CharField(
        label=_('Message'),
        widget=forms.Textarea
    )
    
    def clean_message(self):
        message = self.cleaned_data['message']
        if len(message) < 10:
            raise forms.ValidationError(
                _('Message must be at least 10 characters long')
            )
        return message

# Template translations
# myapp/templates/home.html

{% load i18n %}

<!DOCTYPE html>
<html lang="{{ LANGUAGE_CODE }}">
<head>
    <title>{% trans "My Website" %}</title>
</head>
<body>
    <h1>{% trans "Welcome!" %}</h1>
    
    <!-- Translation with variables -->
    <p>{% blocktrans with name=user.username %}
        Hello, {{ name }}! Nice to see you.
    {% endblocktrans %}</p>
    
    <!-- Plural forms in templates -->
    <p>{% blocktrans count counter=items|length %}
        You have {{ counter }} item.
    {% plural %}
        You have {{ counter }} items.
    {% endblocktrans %}</p>
    
    <!-- Context-specific translation -->
    <p>{% pgettext "month name" "May" %}</p>
    
    <!-- Translation with HTML -->
    <p>{% blocktrans %}
        Visit our <a href="/about/">about page</a> for more information.
    {% endblocktrans %}</p>
    
    <!-- Language switcher -->
    <form action="{% url 'set_language' %}" method="post">
        {% csrf_token %}
        <select name="language">
            {% get_current_language as LANGUAGE_CODE %}
            {% get_available_languages as LANGUAGES %}
            {% for lang_code, lang_name in LANGUAGES %}
                <option value="{{ lang_code }}" 
                    {% if lang_code == LANGUAGE_CODE %}selected{% endif %}>
                    {{ lang_name }}
                </option>
            {% endfor %}
        </select>
        <button type="submit">{% trans "Change language" %}</button>
    </form>
</body>
</html>

# JavaScript translations
# templates/base.html
{% load i18n %}
<script src="{% url 'javascript-catalog' %}"></script>
<script>
    // Use gettext in JavaScript
    alert(gettext('Hello, World!'));
    
    // Interpolation
    var name = 'John';
    alert(interpolate(gettext('Hello, %s!'), [name]));
    
    // Plural forms
    var count = 5;
    alert(ngettext('You have %s message', 'You have %s messages', count));
</script>

# Creating and managing translation files

# Extract translatable strings to .po files
python manage.py makemessages -l es
python manage.py makemessages -l fr
python manage.py makemessages -l de

# Extract from specific directories
python manage.py makemessages -l es --ignore=venv/*

# Extract from JavaScript files
python manage.py makemessages -d djangojs -l es

# Update existing .po files with new strings
python manage.py makemessages -a  # All languages

# Translation file structure
# locale/es/LC_MESSAGES/django.po

# This file is distributed under the same license as the PACKAGE package.
msgid ""
msgstr ""
"Project-Id-Version: \n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-01-24 10:00+0000\n"
"PO-Revision-Date: 2026-01-24 10:30+0000\n"
"Last-Translator: Your Name <[email protected]>\n"
"Language: es\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

# Simple translation
msgid "Welcome to our website"
msgstr "Bienvenido a nuestro sitio web"

# String with variable
msgid "Hello, %(name)s! Welcome back."
msgstr "¡Hola, %(name)s! Bienvenido de nuevo."

# Plural forms
msgid "You have %(count)d item"
msgid_plural "You have %(count)d items"
msgstr[0] "Tienes %(count)d artículo"
msgstr[1] "Tienes %(count)d artículos"

# Context-specific translation
msgctxt "month name"
msgid "May"
msgstr "Mayo"

msgctxt "verb"
msgid "May"
msgstr "Puede"

# Long translation
msgid ""
"This is a very long string that "
"spans multiple lines in the source "
"code."
msgstr ""
"Esta es una cadena muy larga que "
"abarca múltiples líneas en el código "
"fuente."

# Compile .po files to .mo files
python manage.py compilemessages

# Compile specific language
python manage.py compilemessages -l es

# Using translation services
# Export .po files to translation service (e.g., Lokalise, Transifex)
# Import translated .po files back
# Compile to .mo files

# Translation workflow script
# scripts/update_translations.sh
#!/bin/bash

# Extract new strings
echo "Extracting translatable strings..."
python manage.py makemessages -a --ignore=venv/*

# Compile all translations
echo "Compiling message files..."
python manage.py compilemessages

echo "Translation update complete!"

# Automated translation validation
# management/commands/check_translations.py
from django.core.management.base import BaseCommand
import polib
import os

class Command(BaseCommand):
    help = 'Check for untranslated strings'
    
    def handle(self, *args, **options):
        locale_dir = 'locale'
        
        for lang in os.listdir(locale_dir):
            po_file = os.path.join(
                locale_dir, lang, 'LC_MESSAGES', 'django.po'
            )
            
            if os.path.exists(po_file):
                po = polib.pofile(po_file)
                untranslated = po.untranslated_entries()
                
                if untranslated:
                    self.stdout.write(
                        self.style.WARNING(
                            f'{lang}: {len(untranslated)} untranslated strings'
                        )
                    )
                    for entry in untranslated[:5]:  # Show first 5
                        self.stdout.write(f'  - {entry.msgid}')
                else:
                    self.stdout.write(
                        self.style.SUCCESS(
                            f'{lang}: All strings translated'
                        )
                    )

# Language selection and switching

# URL configuration for language switching
# myproject/urls.py
from django.conf.urls.i18n import i18n_patterns
from django.contrib import admin
from django.urls import path, include
from django.conf import settings

urlpatterns = [
    path('i18n/', include('django.conf.urls.i18n')),
]

# Translated URLs
urlpatterns += i18n_patterns(
    path('admin/', admin.site.urls),
    path('', include('myapp.urls')),
    prefix_default_language=True,
)

# URLs will be:
# /en/about/
# /es/acerca-de/
# /fr/a-propos/

# Language switcher view
from django.shortcuts import render
from django.conf import settings

def language_selector(request):
    return render(request, 'language_selector.html', {
        'languages': settings.LANGUAGES,
        'current_language': request.LANGUAGE_CODE,
    })

# Language switcher template
# templates/language_selector.html
{% load i18n %}

<form action="{% url 'set_language' %}" method="post">
    {% csrf_token %}
    <input name="next" type="hidden" value="{{ request.path }}">
    <select name="language" onchange="this.form.submit()">
        {% get_current_language as LANGUAGE_CODE %}
        {% get_available_languages as LANGUAGES %}
        {% for lang_code, lang_name in LANGUAGES %}
            <option value="{{ lang_code }}" 
                {% if lang_code == LANGUAGE_CODE %}selected{% endif %}>
                {{ lang_name }}
            </option>
        {% endfor %}
    </select>
</form>

# Store language preference in user profile
# myapp/models.py
from django.db import models
from django.contrib.auth.models import User

class UserProfile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    language = models.CharField(
        max_length=10,
        choices=settings.LANGUAGES,
        default='en'
    )
    timezone = models.CharField(
        max_length=50,
        default='UTC'
    )

# Custom language middleware
from django.utils import translation
from django.utils.deprecation import MiddlewareMixin

class UserLanguageMiddleware(MiddlewareMixin):
    def process_request(self, request):
        if request.user.is_authenticated:
            try:
                user_language = request.user.userprofile.language
                translation.activate(user_language)
                request.LANGUAGE_CODE = user_language
            except:
                pass

# Language-specific URLs
# myapp/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('about/', views.about, name='about'),
]

# Translate URL patterns
from django.utils.translation import gettext_lazy as _

urlpatterns = [
    path(_('about/'), views.about, name='about'),
]

# JavaScript language detection
<script>
    // Get browser language
    var userLang = navigator.language || navigator.userLanguage;
    console.log('Browser language:', userLang);
    
    // Redirect to appropriate language
    if (userLang.startsWith('es')) {
        window.location.href = '/es/';
    } else if (userLang.startsWith('fr')) {
        window.location.href = '/fr/';
    }
</script>

# Accept-Language header detection (automatic)
# Django's LocaleMiddleware automatically detects:
# 1. Language from URL prefix (/es/, /fr/)
# 2. Language from session
# 3. Language from cookie
# 4. Accept-Language header
# 5. Default LANGUAGE_CODE