# Language Translation System - Quick Start

## What Was Implemented

A complete language translation system for NexusMart that automatically syncs language selection with currency conversion. When users change language, the page translates AND the currency automatically switches to the appropriate region's currency.

## Key Features

✅ **10 Languages Supported**
- English, German, French, Spanish, Chinese, Japanese, Georgian, Russian, Arabic, Portuguese

✅ **Automatic Currency Sync**
- Change language → currency updates automatically
- Change currency → language updates automatically

✅ **Professional UI**
- Language selector in navbar
- Currency selector in navbar
- Real-time price updates

✅ **Right-to-Left Support**
- Automatic detection for Arabic, Hebrew, Urdu, Farsi

✅ **Persistent Sessions**
- Language and currency preferences saved in session
- Survives page refreshes

## Quick Start - 5 Steps

### Step 1: Generate Translation Files
```bash
cd c:\Users\Imokeuklemi\development_projects\nexusmart
python manage.py makemessages -l de
python manage.py makemessages -l zh
python manage.py makemessages -l ja
```

### Step 2: Open Translation Files
```
locale/de/LC_MESSAGES/django.po  (German)
locale/zh/LC_MESSAGES/django.po  (Chinese)
locale/ja/LC_MESSAGES/django.po  (Japanese)
```

### Step 3: Translate Strings
Each `.po` file contains entries like:
```
#: templates/navbar.html:45
msgid "Add to Cart"
msgstr "[YOUR TRANSLATION HERE]"
```

### Step 4: Compile Translations
```bash
python manage.py compilemessages
```

### Step 5: Test
```bash
python manage.py runserver
# Visit http://localhost:8000
# Click language dropdown in navbar
# Verify page translates AND currency syncs
```

## Files Modified/Created

### Configuration Files
- ✏️ `nexusmart/settings.py` - Added language configuration and middleware

### New Files Created
- 📄 `shop/language_views.py` - Language/currency switching views
- 📄 `shop/translation_utils.py` - Helper utilities
- 📄 `shop/templatetags/i18n_filters.py` - Custom template filters
- 📄 `templates/language_selector.html` - Reusable selector component
- 📄 `LANGUAGE_TRANSLATION_GUIDE.md` - Comprehensive guide

### Updated Files
- ✏️ `shop/middleware.py` - Added LanguageCurrencySyncMiddleware
- ✏️ `shop/context_processors.py` - Added language context processor
- ✏️ `shop/urls.py` - Added language/currency switching routes
- ✏️ `templates/navbar.html` - Added language selector and improved UI

### Auto-Generated (After makemessages)
- 📁 `locale/` - Translation directory structure
  - `locale/[lang]/LC_MESSAGES/django.po` - Translatable strings
  - `locale/[lang]/LC_MESSAGES/django.mo` - Compiled translations

## Language-Currency Mapping

| Language | Currency |
|----------|----------|
| English (en) | USD ($) |
| German (de) | EUR (€) |
| French (fr) | EUR (€) |
| Spanish (es) | EUR (€) |
| Chinese (zh) | CNY (¥) |
| Japanese (ja) | JPY (¥) |
| Georgian (ka) | GEL (₾) |
| Russian (ru) | EUR (€) |
| Arabic (ar) | USD ($) |
| Portuguese (pt) | EUR (€) |

## Using Django i18n Tags in Templates

```django
{% load i18n %}

{# Simple translation #}
<h1>{% trans "Welcome to BanshiX" %}</h1>

{# Translation with variables #}
<p>{% blocktrans %}Hello {{ user.name }}{% endblocktrans %}</p>

{# Plural forms #}
{% blocktrans count counter=items %}
  You have 1 item.
{% plural %}
  You have {{ counter }} items.
{% endblocktrans %}
```

## Available Endpoints

```
GET/POST /set-language/              - Set language via form parameter
GET      /set-language/<code>/       - Set language directly
GET/POST /set-currency/              - Set currency via form parameter
GET      /set-currency/<code>/       - Set currency directly
GET      /api/languages/             - Get all languages as JSON
```

## URL Examples

```
/set-language/de/               # Switch to German (USD→EUR, lang→de)
/set-currency/JPY/              # Switch to Japanese Yen (lang→ja, curr→JPY)
/api/languages/                 # Get: {"languages": [...], "current_language": "en", ...}
```

## Testing Workflow

1. **Test Language Change**
   - Click language dropdown
   - Select "Deutsch" (German)
   - Verify: Page language changes + currency changes to EUR
   - Check: All prices update with EUR conversion

2. **Test Currency Change**
   - Click currency dropdown
   - Select "¥ CNY - Chinese Yuan"
   - Verify: Currency changes to CNY + language changes to Chinese
   - Check: All prices update with CNY conversion

3. **Test Session Persistence**
   - Set language to German
   - Refresh page
   - Verify: Language and currency stay as set

## Common Tasks

### Add a New Language
1. Add to `LANGUAGES` in `nexusmart/settings.py`
2. Add mapping to `LANGUAGE_CURRENCY_MAPPING` 
3. Run: `python manage.py makemessages -l [code]`
4. Translate strings in `locale/[code]/LC_MESSAGES/django.po`
5. Run: `python manage.py compilemessages`

### Add Translatable String to Template
```django
{% load i18n %}
<button>{% trans "Click Me" %}</button>
```

### Add Translatable String to Python
```python
from django.utils.translation import gettext as _
message = _("This will be translated")
```

### Mark String Plural-Ready
```django
{% blocktrans count counter=count %}
  {{ counter }} item
{% plural %}
  {{ counter }} items
{% endblocktrans %}
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Translations not showing | Run `python manage.py compilemessages` |
| Language not changing | Check `LANGUAGE_CURRENCY_MAPPING` has the language |
| Prices not updating | Ensure elements have `data-price` attribute |
| Currency not syncing | Check middleware order and `LanguageCurrencySyncMiddleware` |

## Database Migrations (if needed)

No database migrations needed! The system uses Django sessions which are already configured.

## Performance Notes

- ⚡ Language switching: Instant (uses session)
- ⚡ Price updates: Real-time (JavaScript)
- ⚡ No additional database queries
- ⚡ Minimal server load

## Next Steps

1. **Translate Content**
   ```bash
   python manage.py makemessages --all
   # Translate all .po files
   python manage.py compilemessages
   ```

2. **Mark Strings for Translation**
   - Add `{% trans %}` to templates
   - Add `_()` to Python views
   - Re-run makemessages

3. **Monitor Translation Coverage**
   - Check `locale/*/LC_MESSAGES/django.po`
   - Ensure all UI strings are covered

4. **Test in Production**
   - Deploy and test with real users
   - Gather feedback
   - Update translations as needed

## Support Resources

- Django i18n Docs: https://docs.djangoproject.com/en/stable/topics/i18n/
- Translation Format: https://docs.djangoproject.com/en/stable/topics/i18n/translation/
- Full Guide: See `LANGUAGE_TRANSLATION_GUIDE.md`

---

**Status**: ✅ Ready to Use  
**Created**: May 4, 2026  
**Maintenance**: Low (translations auto-sync across site)