# NexusMart Internationalization (i18n) Setup Guide

## 📋 Overview

Your NexusMart website now has full internationalization support for **10 languages**:
- 🇺🇸 English (en)
- 🇩🇪 Deutsch (de) 
- 🇫🇷 Français (fr)
- 🇪🇸 Español (es)
- 🇨🇳 中文 (zh)
- 🇯🇵 日本語 (ja)
- 🇬🇪 ქართული (ka)
- 🇷🇺 Русский (ru)
- 🇸🇦 العربية (ar) - RTL Support
- 🇵🇹 Português (pt)

## ✅ What's Been Configured

### 1. **Django Settings** ✅
- `USE_I18N = True` - Internationalization enabled
- `LOCALE_PATHS` - Points to `locale/` directory
- All 10 languages registered in `LANGUAGES` setting
- `LANGUAGE_CODE = "en"` - Default language
- `LANGUAGE_CURRENCY_MAPPING` - Auto-sync language to currency

### 2. **URL Configuration** ✅
- Language-prefixed URLs: `/en/products/`, `/de/products/`, etc.
- Uses Django's `i18n_patterns()` for clean URL structure
- SEO-friendly with language prefix support

### 3. **Template Support** ✅
- `{% load i18n %}` tags added to all major templates
- `{% trans %}` tags for translatable strings
- `{% blocktrans %}` for longer text blocks
- HTML `lang` attribute dynamically set: `<html lang="{{ LANGUAGE_CODE }}">`
- RTL support for Arabic: `dir="{% if LANGUAGE_BIDI %}rtl{% else %}ltr{% endif %}"`

### 4. **Middleware & Context Processors** ✅
- `LocaleMiddleware` - Detects language from URL, session, cookies
- `LanguageCurrencySyncMiddleware` - Auto-syncs language to currency
- Context processor provides language metadata to all templates
- `LANGUAGE_BIDI` flag for RTL language support

### 5. **Python Translation Strings** ✅
- `gettext_lazy` imported in views.py and admin.py
- Admin interface strings wrapped with `_()` for translation
- Ready for translatable error/success messages

## 🚀 How to Generate Translation Files

### Step 1: Create Translation Template
```bash
python manage.py makemessages -a
```
This creates `.po` files in `locale/{lang}/LC_MESSAGES/` for all configured languages.

### Step 2: Translate Strings
Open translation files with a PO editor (e.g., Poedit, VS Code with i18n extension):
- `locale/de/LC_MESSAGES/django.po` - German translations
- `locale/fr/LC_MESSAGES/django.po` - French translations
- `locale/es/LC_MESSAGES/django.po` - Spanish translations
- etc.

### Step 3: Compile Translations
```bash
python manage.py compilemessages
```
This creates `.mo` files that Django uses at runtime.

### Step 4: Restart Server
```bash
python manage.py runserver
```

## 📁 Translation File Structure
```
locale/
├── de/
│   └── LC_MESSAGES/
│       ├── django.po      # German translation source
│       └── django.mo      # Compiled German translations (binary)
├── fr/
│   └── LC_MESSAGES/
│       ├── django.po      # French translation source
│       └── django.mo
├── es/
├── zh/
├── ja/
├── ka/
├── ru/
├── ar/
└── pt/
    └── LC_MESSAGES/
        ├── django.po
        └── django.mo
```

## 🔧 How Language Switching Works

1. **User selects language** in navbar dropdown
2. **POST to `/set-language/<lang>/`** or `/set-language/` with language parameter
3. **Language stored in session**: `request.session['django_language'] = language`
4. **Middleware detects language** from session on next request
5. **Templates/Views use current language** via `django.utils.translation.get_language()`
6. **Currency auto-syncs** based on `LANGUAGE_CURRENCY_MAPPING`

## 🌍 URL Examples

### English
- `/en/` - Home
- `/en/products/` - Products
- `/en/product/my-product/` - Product detail
- `/en/contact/` - Contact

### German
- `/de/` - Home
- `/de/products/` - Products
- `/de/product/my-product/` - Product detail
- `/de/contact/` - Contact

### Arabic (RTL)
- `/ar/` - Home with RTL layout
- Direction automatically set to `rtl` for Arabic

## 📱 Mobile Responsiveness

All translations work seamlessly with responsive design:
- Mobile, tablet, desktop all support language switching
- Language selector in navbar works on all screen sizes
- Collapsible features/descriptions translate in all languages
- Heart wishlist button works globally

## 🎯 What Needs Translation

### Already Wrapped (Ready for translation):
- ✅ Page titles and headings
- ✅ Button labels
- ✅ Form fields
- ✅ Admin interface
- ✅ Footer content
- ✅ Contact page

### Needs Manual Translation in PO Files:
- Product descriptions (from database - handle separately if needed)
- User-generated content
- Email templates (can add `{% trans %}` tags)

## 📝 Example Translation Workflow

### Template Example:
```django
{% trans "Welcome to BanshiX" %}
{% trans "Add to Cart" %}
{% trans "Our Products" %}
```

### Python Example:
```python
from django.utils.translation import gettext_lazy as _

message = _("Product added successfully!")
messages.success(request, message)
```

## 🧪 Testing Language Switching

1. **Browser Dev Tools**:
   - Navigate to `/de/products/` - should display German
   - Navigate to `/fr/products/` - should display French
   - Navigate to `/ar/` - should display Arabic RTL layout

2. **Language Dropdown**:
   - Click language selector in navbar
   - Page should refresh in selected language
   - Currency should auto-update per language

3. **Session Persistence**:
   - Select German
   - Navigate to any page - should stay German
   - Close and reopen browser - language persists in session

## 🔗 Important Files for i18n

| File | Purpose |
|------|---------|
| `nexusmart/settings.py` | Language config, currency mapping |
| `nexusmart/urls.py` | URL i18n patterns setup |
| `shop/context_processors.py` | Language context for templates |
| `shop/language_views.py` | Language/currency switching views |
| `shop/middleware.py` | Language detection and syncing |
| `templates/base.html` | Dynamic HTML lang attribute |
| `templates/navbar.html` | Language selector dropdown |
| `locale/` | Translation files (to be generated) |

## ⚙️ Automatic Features

### Language → Currency Sync:
```python
LANGUAGE_CURRENCY_MAPPING = {
    'en': 'USD',     # English → US Dollar
    'de': 'EUR',     # German → Euro
    'fr': 'EUR',     # French → Euro
    'zh': 'CNY',     # Chinese → Chinese Yuan
    'ja': 'JPY',     # Japanese → Japanese Yen
    'ar': 'USD',     # Arabic → US Dollar
    'pt': 'EUR',     # Portuguese → Euro
    # ... etc
}
```

When user selects German (de), currency automatically switches to EUR (€).

## 🚧 Future Enhancements

1. **Database Translations**: 
   - Use `django-modeltranslation` for product descriptions in multiple languages
   - Or use `django-parler` for transparent multilingual support

2. **Automated Translation**:
   - Integrate Google Translate API for auto-translation
   - Use Azure Translator service

3. **Language Persistence**:
   - Store language preference in user profile (for logged-in users)
   - Create cookie-based fallback

4. **RTL Improvements**:
   - Add RTL-specific CSS styles for Arabic/Hebrew
   - Test all pages in RTL mode

## 📚 Quick Commands

```bash
# Generate translation templates for all languages
python manage.py makemessages -a

# Generate translations for specific language
python manage.py makemessages -l de

# Compile all translations to .mo files
python manage.py compilemessages

# Check for untranslated strings
python manage.py makemessages -a --no-wrap

# Update existing translations
python manage.py makemessages -a --update
```

## ✨ Next Steps

1. **Run `python manage.py makemessages -a`** to generate .po files
2. **Open locale/*/LC_MESSAGES/django.po** files in a PO editor
3. **Translate strings** from English to target language
4. **Run `python manage.py compilemessages`** to compile
5. **Test each language** in browser
6. **Commit translation files** to git

---

**Status**: ✅ Infrastructure Complete | ⏳ Translations Pending

The internationalization system is fully configured and ready for translations!
