# Translation QuickStart Guide

Get your NexusMart website translating in 5 minutes.

## Prerequisites

- ✅ Django 5.1 with i18n configured
- ✅ 10 languages configured
- ✅ All templates have `{% load i18n %}` tags
- ✅ All Python strings wrapped with `_()` or `gettext_lazy()`

## 5-Minute Setup

### 1️⃣ Generate Translation Files (2 min)

```bash
cd c:\Users\Imokeuklemi\development_projects\nexusmart
python manage.py makemessages -a
```

**What this does**:
- Scans all `.py` and `.html` files for translatable strings
- Creates `.po` files in `locale/{lang}/LC_MESSAGES/django.po`
- One file per language (e.g., `locale/de/LC_MESSAGES/django.po`)

**Expected output**:
```
processing language de
processing language fr
processing language es
processing language zh
processing language ja
processing language ka
processing language ru
processing language ar
processing language pt
```

### 2️⃣ Check Generated Files (1 min)

```bash
dir locale\*/LC_MESSAGES\django.po
```

You should see 9 files (one per non-English language).

Each file looks like:
```
#: templates/base.html:42
msgid "Add to Cart"
msgstr ""

#: templates/navbar.html:18
msgid "Welcome to BanshiMart"
msgstr ""
```

### 3️⃣ Translate Strings (0-90 min depending on scope)

**Option A: Quick Testing (5 min)**
- Edit `locale/de/LC_MESSAGES/django.po`
- Find first 5 empty `msgstr` fields
- Add German translations:
```
msgstr "In den Warenkorb"    # for "Add to Cart"
msgstr "Willkommen"            # for "Welcome"
msgstr "Produkte"              # for "Products"
```

**Option B: Full Translation (hours)**
- Use Poedit (recommended):
  - Download: https://poedit.net
  - Open `locale/de/LC_MESSAGES/django.po`
  - Click "Edit Translation"
  - Fill in all `msgstr` fields
  - Save

- Or VS Code:
  - Install extension: "i18n Ally" or "gettext"
  - Open `.po` files
  - Edit translations inline

### 4️⃣ Compile Translations (1 min)

```bash
python manage.py compilemessages
```

**What this does**:
- Converts `.po` files to `.mo` (binary format)
- Django uses `.mo` files at runtime
- Much faster than reading `.po` files

**Expected output**:
```
processing language de
processing language fr
processing language es
...
```

### 5️⃣ Restart & Test (1 min)

```bash
python manage.py runserver
```

Then test in browser:
- http://localhost:8000/en/ → English
- http://localhost:8000/de/ → German (with your translations)
- http://localhost:8000/fr/ → French (placeholder strings)

---

## Common Translation Scenarios

### Scenario 1: Translate Only German & French

```bash
# Generate for specific languages
python manage.py makemessages -l de
python manage.py makemessages -l fr

# Edit files
# locale/de/LC_MESSAGES/django.po
# locale/fr/LC_MESSAGES/django.po

# Compile
python manage.py compilemessages
```

### Scenario 2: Add New Translatable Strings

```python
# In views.py
from django.utils.translation import gettext_lazy as _

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

```django
{# In templates #}
{% load i18n %}
{% trans "Product added!" %}
```

Then regenerate:
```bash
python manage.py makemessages -a --update
```

### Scenario 3: Check Translation Progress

```bash
# Count translated strings
grep -c "msgstr \"" locale/de/LC_MESSAGES/django.po
grep -c "msgstr \"\"" locale/de/LC_MESSAGES/django.po
```

---

## Translation Tools Comparison

| Tool | Cost | Ease | Features |
|------|------|------|----------|
| **Poedit** | Free (limited) / $49 | ⭐⭐⭐⭐ | Best overall, context hints, TM |
| **VS Code + i18n Ally** | Free | ⭐⭐⭐ | Inline editing, file tree view |
| **GTranslator** | Free | ⭐⭐⭐ | Linux native, simple UI |
| **Text Editor** | Free | ⭐ | Tedious but works |
| **Google Translate API** | Paid | ⭐⭐ | Auto-translation (quality varies) |

**Recommendation**: Use Poedit for professional translation

---

## Translation Tips for Best Results

### 1. Context Matters
```
"Order" in "Place an order" → "Bestellung aufgeben"
"Order" in "Your orders" → "Meine Bestellungen"
```

### 2. Keep It Concise
- Button labels: < 3 words
- Headings: < 5 words
- Descriptions: Translate accurately, conciseness is secondary

### 3. Test Translations
- View website in target language
- Check button/label sizes
- Verify forms render correctly
- Test RTL layout for Arabic

### 4. Use Glossary for Consistency
Create a file like `GLOSSARY.md`:
```
Products → Produkte (not Waren)
Cart → Warenkorb (not Einkaufswagen)
Checkout → Kasse (not Bezahlung)
```

### 5. RTL Languages (Arabic)
- Direction is auto-handled by CSS
- Keep text reasonably short
- Test layout in browser

---

## Troubleshooting

### Problem: `.po` files not generated

**Cause**: `makemessages` needs at least one translatable string

**Solution**: 
```bash
# Add this to a template
{% trans "Hello World" %}

# Try again
python manage.py makemessages -a
```

### Problem: Translations not showing

**Cause**: Forgot to run `compilemessages` or didn't restart server

**Solution**:
```bash
python manage.py compilemessages
python manage.py runserver
```

### Problem: Untranslated strings still appear

**Cause**: String not wrapped with `{% trans %}` or `_()`

**Solution**:
1. Find the string in code
2. Wrap it: `{% trans "string" %}` or `_("string")`
3. Run `makemessages -a`
4. Translate in `.po` file
5. Run `compilemessages`

### Problem: `.po` file too large

**Cause**: Normal for large projects (100+ strings)

**Solution**:
- Use Poedit to manage (filters, search)
- Focus on high-priority strings first
- Auto-translate secondary content later

---

## Next Steps After Initial Translation

1. **Test All Languages**
   ```
   /en/products  → English
   /de/products  → Deutsch
   /fr/products  → Français
   /es/products  → Español
   /ar/products  → العربية (RTL test)
   ```

2. **Set Up Language Selector**
   - Navbar dropdown works automatically
   - Language persists in session

3. **Auto-Sync Currency**
   ```
   German (de) → EUR (€)
   Chinese (zh) → CNY (¥)
   French (fr) → EUR (€)
   ```

4. **Translate Dynamic Content** (Optional)
   - Product descriptions (use django-modeltranslation)
   - User-generated content
   - Email templates

5. **Set Up Regular Translation Updates**
   - When you add new features/strings:
     ```bash
     python manage.py makemessages -a --update
     ```
   - Update `.po` files with new translations
   - Compile and deploy

---

## PO File Format Reference

A `.po` file contains entries like:

```
#: templates/navbar.html:15
#: templates/base.html:42
msgid "Add to Cart"
msgstr "In den Warenkorb"
```

- `#:` = File and line number where string appears
- `msgid` = Original English string
- `msgstr` = Translated string (leave empty for untranslated)

### Marking Strings

**Fuzzy** (uncertain translation):
```
#, fuzzy
msgid "String"
msgstr "Translated"
```

**Comments for translators**:
```
#. This is a button label, keep it short
msgid "Submit"
msgstr ""
```

---

## Commands Cheat Sheet

```bash
# Generate all translation files
python manage.py makemessages -a

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

# Update existing files with new strings
python manage.py makemessages -a --update

# Compile translations
python manage.py compilemessages

# Check for missing translations
python manage.py makemessages -a --check-changes

# Generate without fuzzy
python manage.py makemessages -a --no-fuzzy

# Test a specific language
# (see strings without translations)
python manage.py makemessages -l de -v 3
```

---

## Getting Help

- **Django i18n Docs**: https://docs.djangoproject.com/en/5.1/topics/i18n/
- **Poedit Help**: https://poedit.net/help
- **i18n Ally (VS Code)**: https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally

---

**Status**: ✅ Ready for Translation

You're all set! Start with Step 1 above and you'll have a multilingual website running.