feat: add multi-language (i18n) support for vendor dashboard and storefront
- Add database fields for language preferences: - Vendor: dashboard_language, storefront_language, storefront_languages - User: preferred_language - Customer: preferred_language - Add language middleware for request-level language detection: - Cookie-based persistence - Browser Accept-Language fallback - Vendor storefront language constraints - Add language API endpoints (/api/v1/language/*): - POST /set - Set language preference - GET /current - Get current language info - GET /list - List available languages - DELETE /clear - Clear preference - Add i18n utilities (app/utils/i18n.py): - JSON-based translation loading - Jinja2 template integration - Language resolution helpers - Add reusable language selector macros for templates - Add languageSelector() Alpine.js component - Add translation files (en, fr, de, lb) in static/locales/ - Add architecture rules documentation for language implementation - Update marketplace-product-detail.js to use native language names 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
551
docs/architecture/language-i18n.md
Normal file
551
docs/architecture/language-i18n.md
Normal file
@@ -0,0 +1,551 @@
|
||||
# Language & Internationalization (i18n) Architecture
|
||||
|
||||
This document defines **strict rules** for implementing language support across the Wizamart platform.
|
||||
|
||||
> **IMPORTANT:** These rules are mandatory. Violations will cause runtime errors, inconsistent UX, or security issues.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Supported Languages](#supported-languages)
|
||||
2. [Language Context Flow](#language-context-flow)
|
||||
3. [Database Schema Rules](#database-schema-rules)
|
||||
4. [Frontend Rules](#frontend-rules)
|
||||
5. [API Rules](#api-rules)
|
||||
6. [Template Rules](#template-rules)
|
||||
7. [JavaScript Rules](#javascript-rules)
|
||||
8. [Translation File Rules](#translation-file-rules)
|
||||
|
||||
---
|
||||
|
||||
## Supported Languages
|
||||
|
||||
| Code | Language | Flag Code | Notes |
|
||||
|------|----------|-----------|-------|
|
||||
| `en` | English | `gb` | Fallback language |
|
||||
| `fr` | French | `fr` | Default for Luxembourg |
|
||||
| `de` | German | `de` | Second official language |
|
||||
| `lb` | Luxembourgish | `lu` | Native language |
|
||||
|
||||
**Rule LANG-001: Only Use Supported Language Codes**
|
||||
|
||||
```python
|
||||
# ✅ GOOD: Use supported codes
|
||||
SUPPORTED_LANGUAGES = ["en", "fr", "de", "lb"]
|
||||
|
||||
# ❌ BAD: Invalid codes
|
||||
language = "english" # ❌ Use "en"
|
||||
language = "french" # ❌ Use "fr"
|
||||
language = "lux" # ❌ Use "lb"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Language Context Flow
|
||||
|
||||
### Resolution Priority
|
||||
|
||||
Language is resolved in this order (highest to lowest priority):
|
||||
|
||||
1. **URL parameter** (`?lang=fr`)
|
||||
2. **Cookie** (`wizamart_language`)
|
||||
3. **User preference** (database: `preferred_language`)
|
||||
4. **Vendor default** (database: `storefront_language` or `dashboard_language`)
|
||||
5. **Accept-Language header** (browser)
|
||||
6. **Platform default** (`fr`)
|
||||
|
||||
### Vendor Dashboard vs Storefront
|
||||
|
||||
| Context | Language Source | Database Field |
|
||||
|---------|-----------------|----------------|
|
||||
| Vendor Dashboard | Vendor's `dashboard_language` | `vendors.dashboard_language` |
|
||||
| Customer Storefront | Vendor's `storefront_language` | `vendors.storefront_language` |
|
||||
| Admin Panel | User's `preferred_language` | `users.preferred_language` |
|
||||
|
||||
---
|
||||
|
||||
## Database Schema Rules
|
||||
|
||||
### Rule DB-001: Vendor Language Fields Are Required
|
||||
|
||||
**Vendors MUST have these language columns with defaults:**
|
||||
|
||||
```python
|
||||
# ✅ GOOD: All language fields with defaults
|
||||
class Vendor(Base):
|
||||
default_language = Column(String(5), nullable=False, default="fr")
|
||||
dashboard_language = Column(String(5), nullable=False, default="fr")
|
||||
storefront_language = Column(String(5), nullable=False, default="fr")
|
||||
storefront_languages = Column(JSON, nullable=False, default=["fr", "de", "en"])
|
||||
```
|
||||
|
||||
```python
|
||||
# ❌ BAD: Nullable language fields
|
||||
class Vendor(Base):
|
||||
default_language = Column(String(5), nullable=True) # ❌ Must have default
|
||||
```
|
||||
|
||||
### Rule DB-002: User/Customer Preferred Language Is Optional
|
||||
|
||||
```python
|
||||
# ✅ GOOD: Optional with fallback logic
|
||||
class User(Base):
|
||||
preferred_language = Column(String(5), nullable=True) # Falls back to vendor/platform default
|
||||
|
||||
class Customer(Base):
|
||||
preferred_language = Column(String(5), nullable=True) # Falls back to storefront_language
|
||||
```
|
||||
|
||||
### Rule DB-003: Pydantic Schemas Must Handle Missing Language Fields
|
||||
|
||||
```python
|
||||
# ✅ GOOD: Optional in response with defaults
|
||||
class VendorResponse(BaseModel):
|
||||
default_language: str = "fr"
|
||||
dashboard_language: str = "fr"
|
||||
storefront_language: str = "fr"
|
||||
storefront_languages: list[str] = ["fr", "de", "en"]
|
||||
|
||||
# ❌ BAD: Required without defaults (breaks backward compatibility)
|
||||
class VendorResponse(BaseModel):
|
||||
default_language: str # ❌ Will fail if DB doesn't have value
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontend Rules
|
||||
|
||||
### Rule FE-001: NEVER Use Inline Complex Alpine.js Data for Language Selector
|
||||
|
||||
**Move complex JavaScript objects to functions. Inline x-data with Jinja breaks JSON serialization.**
|
||||
|
||||
```html
|
||||
<!-- ❌ BAD: Inline complex object with Jinja variable -->
|
||||
<div x-data="{
|
||||
isLangOpen: false,
|
||||
currentLang: '{{ request.state.language }}',
|
||||
languages: {{ enabled_langs }}, <!-- ❌ Jinja outputs Python list, not JSON -->
|
||||
async setLanguage(lang) {
|
||||
// Complex function here
|
||||
}
|
||||
}">
|
||||
```
|
||||
|
||||
```html
|
||||
<!-- ✅ GOOD: Use function with tojson|safe filter -->
|
||||
<div x-data="languageSelector('{{ request.state.language|default("fr") }}', {{ enabled_langs|tojson|safe }})">
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ GOOD: Define function in JavaScript file
|
||||
function languageSelector(currentLang, enabledLanguages) {
|
||||
return {
|
||||
isLangOpen: false,
|
||||
currentLang: currentLang || 'fr',
|
||||
languages: enabledLanguages || ['fr', 'de', 'en'],
|
||||
languageNames: {
|
||||
'en': 'English',
|
||||
'fr': 'Français',
|
||||
'de': 'Deutsch',
|
||||
'lb': 'Lëtzebuergesch'
|
||||
},
|
||||
languageFlags: {
|
||||
'en': 'gb',
|
||||
'fr': 'fr',
|
||||
'de': 'de',
|
||||
'lb': 'lu'
|
||||
},
|
||||
async setLanguage(lang) {
|
||||
// Implementation
|
||||
}
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Rule FE-002: Always Use tojson|safe for Python Lists in JavaScript
|
||||
|
||||
```html
|
||||
<!-- ❌ BAD: Raw Jinja output -->
|
||||
<div x-data="{ languages: {{ vendor.storefront_languages }} }">
|
||||
<!-- Outputs: ['fr', 'de'] - Python syntax, invalid JavaScript -->
|
||||
|
||||
<!-- ❌ BAD: tojson without safe -->
|
||||
<div x-data="{ languages: {{ vendor.storefront_languages|tojson }} }">
|
||||
<!-- May escape quotes to " in HTML context -->
|
||||
|
||||
<!-- ✅ GOOD: tojson with safe -->
|
||||
<div x-data="{ languages: {{ vendor.storefront_languages|tojson|safe }} }">
|
||||
<!-- Outputs: ["fr", "de"] - Valid JSON/JavaScript -->
|
||||
```
|
||||
|
||||
### Rule FE-003: Language Selector Must Be In Shared JavaScript
|
||||
|
||||
**Language selector function MUST be defined in:**
|
||||
- `static/shop/js/shop-layout.js` for storefront
|
||||
- `static/vendor/js/init-alpine.js` for vendor dashboard
|
||||
|
||||
```javascript
|
||||
// ✅ GOOD: Reusable function with consistent implementation
|
||||
function languageSelector(currentLang, enabledLanguages) {
|
||||
return {
|
||||
isLangOpen: false,
|
||||
currentLang: currentLang || 'fr',
|
||||
languages: enabledLanguages || ['en', 'fr', 'de', 'lb'],
|
||||
languageNames: {
|
||||
'en': 'English',
|
||||
'fr': 'Français',
|
||||
'de': 'Deutsch',
|
||||
'lb': 'Lëtzebuergesch'
|
||||
},
|
||||
languageFlags: {
|
||||
'en': 'gb',
|
||||
'fr': 'fr',
|
||||
'de': 'de',
|
||||
'lb': 'lu'
|
||||
},
|
||||
async setLanguage(lang) {
|
||||
if (lang === this.currentLang) {
|
||||
this.isLangOpen = false;
|
||||
return;
|
||||
}
|
||||
try {
|
||||
const response = await fetch('/api/v1/language/set', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ language: lang })
|
||||
});
|
||||
if (response.ok) {
|
||||
this.currentLang = lang;
|
||||
window.location.reload();
|
||||
}
|
||||
} catch (error) {
|
||||
console.error('Failed to set language:', error);
|
||||
}
|
||||
this.isLangOpen = false;
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
window.languageSelector = languageSelector;
|
||||
```
|
||||
|
||||
### Rule FE-004: Storefront Must Respect Vendor's Enabled Languages
|
||||
|
||||
```html
|
||||
<!-- ✅ GOOD: Only show languages enabled by vendor -->
|
||||
{% set enabled_langs = vendor.storefront_languages if vendor and vendor.storefront_languages else ['fr', 'de', 'en'] %}
|
||||
{% if enabled_langs|length > 1 %}
|
||||
<div x-data="languageSelector('{{ request.state.language|default("fr") }}', {{ enabled_langs|tojson|safe }})">
|
||||
<!-- Language selector UI -->
|
||||
</div>
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
```html
|
||||
<!-- ❌ BAD: Hardcoded language list ignoring vendor settings -->
|
||||
<div x-data="languageSelector('fr', ['en', 'fr', 'de', 'lb'])">
|
||||
<!-- Shows all languages regardless of vendor config -->
|
||||
</div>
|
||||
```
|
||||
|
||||
### Rule FE-005: Vendor Dashboard Shows All Languages
|
||||
|
||||
```html
|
||||
<!-- ✅ GOOD: Vendor dashboard always shows all 4 languages -->
|
||||
<div x-data="languageSelector('{{ request.state.language|default("fr") }}', ['en', 'fr', 'de', 'lb'])">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Rules
|
||||
|
||||
### Rule API-001: Language Endpoint Must Set Cookie
|
||||
|
||||
```python
|
||||
# ✅ GOOD: Set both cookie and return JSON
|
||||
@router.post("/language/set")
|
||||
async def set_language(request: LanguageSetRequest, response: Response):
|
||||
if request.language not in SUPPORTED_LANGUAGES:
|
||||
raise HTTPException(status_code=400, detail="Unsupported language")
|
||||
|
||||
response.set_cookie(
|
||||
key="wizamart_language",
|
||||
value=request.language,
|
||||
max_age=365 * 24 * 60 * 60, # 1 year
|
||||
httponly=True,
|
||||
samesite="lax"
|
||||
)
|
||||
return {"success": True, "language": request.language}
|
||||
```
|
||||
|
||||
### Rule API-002: Validate Language Codes
|
||||
|
||||
```python
|
||||
# ✅ GOOD: Strict validation
|
||||
SUPPORTED_LANGUAGES = {"en", "fr", "de", "lb"}
|
||||
|
||||
class LanguageSetRequest(BaseModel):
|
||||
language: str = Field(..., pattern="^(en|fr|de|lb)$")
|
||||
|
||||
# ❌ BAD: No validation
|
||||
class LanguageSetRequest(BaseModel):
|
||||
language: str # ❌ Accepts any string
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template Rules
|
||||
|
||||
### Rule TPL-001: Always Provide Language Default
|
||||
|
||||
```html
|
||||
<!-- ✅ GOOD: Default value -->
|
||||
{{ request.state.language|default("fr") }}
|
||||
|
||||
<!-- ❌ BAD: No default -->
|
||||
{{ request.state.language }} <!-- ❌ May be None -->
|
||||
```
|
||||
|
||||
### Rule TPL-002: Check Language Array Length Before Rendering Selector
|
||||
|
||||
```html
|
||||
<!-- ✅ GOOD: Only show if multiple languages -->
|
||||
{% if enabled_langs|length > 1 %}
|
||||
<!-- Language selector -->
|
||||
{% endif %}
|
||||
|
||||
<!-- ❌ BAD: Always show even with single language -->
|
||||
<!-- Language selector shown with only 1 option -->
|
||||
```
|
||||
|
||||
### Rule TPL-003: Use Consistent Flag Icon Classes
|
||||
|
||||
```html
|
||||
<!-- ✅ GOOD: Use flag-icons library consistently -->
|
||||
<span class="fi fi-{{ flag_code }}"></span>
|
||||
|
||||
<!-- Flag codes mapping -->
|
||||
<!-- en → gb (Great Britain) -->
|
||||
<!-- fr → fr (France) -->
|
||||
<!-- de → de (Germany) -->
|
||||
<!-- lb → lu (Luxembourg) -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## JavaScript Rules
|
||||
|
||||
### Rule JS-001: Language Names Must Use Native Language
|
||||
|
||||
```javascript
|
||||
// ✅ GOOD: Native language names
|
||||
languageNames: {
|
||||
'en': 'English',
|
||||
'fr': 'Français', // ✅ Not "French"
|
||||
'de': 'Deutsch', // ✅ Not "German"
|
||||
'lb': 'Lëtzebuergesch' // ✅ Not "Luxembourgish"
|
||||
}
|
||||
|
||||
// ❌ BAD: English names
|
||||
languageNames: {
|
||||
'en': 'English',
|
||||
'fr': 'French', // ❌ Should be "Français"
|
||||
'de': 'German', // ❌ Should be "Deutsch"
|
||||
'lb': 'Luxembourgish' // ❌ Should be "Lëtzebuergesch"
|
||||
}
|
||||
```
|
||||
|
||||
### Rule JS-002: Flag Codes Must Map Correctly
|
||||
|
||||
```javascript
|
||||
// ✅ GOOD: Correct flag mappings
|
||||
languageFlags: {
|
||||
'en': 'gb', // ✅ Great Britain flag for English
|
||||
'fr': 'fr', // ✅ France flag
|
||||
'de': 'de', // ✅ Germany flag
|
||||
'lb': 'lu' // ✅ Luxembourg flag
|
||||
}
|
||||
|
||||
// ❌ BAD: Incorrect mappings
|
||||
languageFlags: {
|
||||
'en': 'us', // ❌ US flag is incorrect for general English
|
||||
'en': 'en', // ❌ 'en' is not a valid flag code
|
||||
'lb': 'lb' // ❌ 'lb' is not a valid flag code
|
||||
}
|
||||
```
|
||||
|
||||
### Rule JS-003: Language API Must Use Correct Endpoint
|
||||
|
||||
```javascript
|
||||
// ✅ GOOD: Correct endpoint
|
||||
fetch('/api/v1/language/set', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ language: lang })
|
||||
});
|
||||
|
||||
// ❌ BAD: Wrong endpoint or method
|
||||
fetch('/api/language/set', ...); // ❌ Missing /v1
|
||||
fetch('/api/v1/language', ...); // ❌ Missing /set
|
||||
fetch('/api/v1/language/set', { method: 'GET' }); // ❌ Should be POST
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Translation File Rules
|
||||
|
||||
### Rule TRANS-001: All Translation Keys Must Exist in All Files
|
||||
|
||||
```
|
||||
static/locales/
|
||||
├── en.json # Must have ALL keys
|
||||
├── fr.json # Must have ALL keys
|
||||
├── de.json # Must have ALL keys
|
||||
└── lb.json # Must have ALL keys
|
||||
```
|
||||
|
||||
### Rule TRANS-002: Translation Files Must Be Valid JSON
|
||||
|
||||
```json
|
||||
// ✅ GOOD: Valid JSON
|
||||
{
|
||||
"common": {
|
||||
"save": "Save",
|
||||
"cancel": "Cancel"
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ BAD: Trailing comma
|
||||
{
|
||||
"common": {
|
||||
"save": "Save",
|
||||
"cancel": "Cancel", // ❌ Trailing comma
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rule TRANS-003: Use Nested Structure for Organization
|
||||
|
||||
```json
|
||||
// ✅ GOOD: Organized by section
|
||||
{
|
||||
"common": {
|
||||
"save": "Sauvegarder",
|
||||
"cancel": "Annuler"
|
||||
},
|
||||
"vendor": {
|
||||
"dashboard": {
|
||||
"title": "Tableau de bord"
|
||||
}
|
||||
},
|
||||
"shop": {
|
||||
"cart": {
|
||||
"empty": "Votre panier est vide"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ BAD: Flat structure
|
||||
{
|
||||
"save": "Sauvegarder",
|
||||
"cancel": "Annuler",
|
||||
"dashboard_title": "Tableau de bord",
|
||||
"cart_empty": "Votre panier est vide"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Language Selector Implementation Checklist
|
||||
|
||||
- [ ] Function defined in appropriate JS file (`shop-layout.js` or `init-alpine.js`)
|
||||
- [ ] Function exported to `window.languageSelector`
|
||||
- [ ] Uses `tojson|safe` filter for language array
|
||||
- [ ] Provides default values for both parameters
|
||||
- [ ] Uses native language names (Français, Deutsch, Lëtzebuergesch)
|
||||
- [ ] Uses correct flag codes (en→gb, fr→fr, de→de, lb→lu)
|
||||
- [ ] Calls `/api/v1/language/set` with POST method
|
||||
- [ ] Reloads page after successful language change
|
||||
- [ ] Hides selector if only one language enabled (storefront)
|
||||
- [ ] Shows all languages (vendor dashboard)
|
||||
|
||||
### Database Column Defaults
|
||||
|
||||
| Table | Column | Type | Default | Nullable |
|
||||
|-------|--------|------|---------|----------|
|
||||
| vendors | default_language | VARCHAR(5) | 'fr' | NO |
|
||||
| vendors | dashboard_language | VARCHAR(5) | 'fr' | NO |
|
||||
| vendors | storefront_language | VARCHAR(5) | 'fr' | NO |
|
||||
| vendors | storefront_languages | JSON | ["fr","de","en"] | NO |
|
||||
| users | preferred_language | VARCHAR(5) | NULL | YES |
|
||||
| customers | preferred_language | VARCHAR(5) | NULL | YES |
|
||||
|
||||
### Files Requiring Language Support
|
||||
|
||||
| File | Type | Notes |
|
||||
|------|------|-------|
|
||||
| `static/shop/js/shop-layout.js` | JS | `languageSelector()` function |
|
||||
| `static/vendor/js/init-alpine.js` | JS | `languageSelector()` function |
|
||||
| `app/templates/shop/base.html` | Template | Storefront language selector |
|
||||
| `app/templates/vendor/partials/header.html` | Template | Dashboard language selector |
|
||||
| `app/api/v1/shared/language.py` | API | Language endpoints |
|
||||
| `middleware/language.py` | Middleware | Language detection |
|
||||
| `static/locales/*.json` | JSON | Translation files |
|
||||
|
||||
---
|
||||
|
||||
## Common Violations and Fixes
|
||||
|
||||
### Violation: Alpine.js Expression Error
|
||||
|
||||
**Symptom:**
|
||||
```
|
||||
Alpine Expression Error: expected expression, got '}'
|
||||
```
|
||||
|
||||
**Cause:** Inline x-data with Jinja template variable not properly escaped.
|
||||
|
||||
**Fix:** Move to function-based approach with `tojson|safe`.
|
||||
|
||||
### Violation: languageFlags is not defined
|
||||
|
||||
**Symptom:**
|
||||
```
|
||||
Uncaught ReferenceError: languageFlags is not defined
|
||||
```
|
||||
|
||||
**Cause:** `languageSelector` function not loaded or not exported.
|
||||
|
||||
**Fix:** Ensure function is defined in JS file and exported to `window.languageSelector`.
|
||||
|
||||
### Violation: Wrong flag displayed
|
||||
|
||||
**Symptom:** US flag shown for English, or no flag for Luxembourgish.
|
||||
|
||||
**Cause:** Incorrect flag code mapping.
|
||||
|
||||
**Fix:** Use correct mappings: `en→gb`, `fr→fr`, `de→de`, `lb→lu`.
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
Add these checks to CI/CD pipeline:
|
||||
|
||||
```bash
|
||||
# Validate translation files are valid JSON
|
||||
python -c "import json; json.load(open('static/locales/en.json'))"
|
||||
python -c "import json; json.load(open('static/locales/fr.json'))"
|
||||
python -c "import json; json.load(open('static/locales/de.json'))"
|
||||
python -c "import json; json.load(open('static/locales/lb.json'))"
|
||||
|
||||
# Check all translation keys exist in all files
|
||||
python scripts/validate_translations.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Language implementation errors cause immediate user-facing issues. Follow these rules strictly.
|
||||
319
docs/development/migration/language-i18n-implementation.md
Normal file
319
docs/development/migration/language-i18n-implementation.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# Language & Internationalization (i18n) Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the implementation of multi-language support for the Wizamart platform. The system supports four languages (English, French, German, Luxembourgish) with flexible configuration at vendor, user, and customer levels.
|
||||
|
||||
## Supported Languages
|
||||
|
||||
| Code | Language | Native Name | Flag |
|
||||
|------|----------|-------------|------|
|
||||
| `en` | English | English | GB |
|
||||
| `fr` | French | Francais | FR |
|
||||
| `de` | German | Deutsch | DE |
|
||||
| `lb` | Luxembourgish | Letzebuerg | LU |
|
||||
|
||||
**Default Language**: French (`fr`) - reflecting the Luxembourg market context.
|
||||
|
||||
## Database Changes
|
||||
|
||||
### Migration: `fcfdc02d5138_add_language_settings_to_vendor_user_customer`
|
||||
|
||||
#### Vendors Table
|
||||
|
||||
New columns added to `vendors`:
|
||||
|
||||
```sql
|
||||
ALTER TABLE vendors ADD COLUMN default_language VARCHAR(5) NOT NULL DEFAULT 'fr';
|
||||
ALTER TABLE vendors ADD COLUMN dashboard_language VARCHAR(5) NOT NULL DEFAULT 'fr';
|
||||
ALTER TABLE vendors ADD COLUMN storefront_language VARCHAR(5) NOT NULL DEFAULT 'fr';
|
||||
ALTER TABLE vendors ADD COLUMN storefront_languages JSON NOT NULL DEFAULT '["fr", "de", "en"]';
|
||||
```
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `default_language` | VARCHAR(5) | Fallback language for content when translation unavailable |
|
||||
| `dashboard_language` | VARCHAR(5) | Default UI language for vendor dashboard |
|
||||
| `storefront_language` | VARCHAR(5) | Default language for customer-facing shop |
|
||||
| `storefront_languages` | JSON | Array of enabled languages for storefront selector |
|
||||
|
||||
#### Users Table
|
||||
|
||||
```sql
|
||||
ALTER TABLE users ADD COLUMN preferred_language VARCHAR(5) NULL;
|
||||
```
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `preferred_language` | VARCHAR(5) | User's preferred dashboard language (overrides vendor setting) |
|
||||
|
||||
#### Customers Table
|
||||
|
||||
```sql
|
||||
ALTER TABLE customers ADD COLUMN preferred_language VARCHAR(5) NULL;
|
||||
```
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `preferred_language` | VARCHAR(5) | Customer's preferred shop language (overrides vendor setting) |
|
||||
|
||||
## Architecture
|
||||
|
||||
### Language Resolution Flow
|
||||
|
||||
#### Vendor Dashboard
|
||||
|
||||
```
|
||||
User preferred_language
|
||||
|
|
||||
v (if not set)
|
||||
Vendor dashboard_language
|
||||
|
|
||||
v (if not set)
|
||||
System DEFAULT_LANGUAGE (fr)
|
||||
```
|
||||
|
||||
#### Storefront
|
||||
|
||||
```
|
||||
Customer preferred_language
|
||||
|
|
||||
v (if not set)
|
||||
Session/Cookie language
|
||||
|
|
||||
v (if not set)
|
||||
Vendor storefront_language
|
||||
|
|
||||
v (if not set)
|
||||
Browser Accept-Language header
|
||||
|
|
||||
v (if not supported)
|
||||
System DEFAULT_LANGUAGE (fr)
|
||||
```
|
||||
|
||||
### Files Created/Modified
|
||||
|
||||
#### New Files
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `app/utils/i18n.py` | Core i18n utilities, translation loading, language resolution |
|
||||
| `middleware/language.py` | Language detection middleware |
|
||||
| `app/api/v1/shared/language.py` | Language API endpoints |
|
||||
| `app/templates/shared/macros/language_selector.html` | UI components for language selection |
|
||||
| `static/locales/en.json` | English translations |
|
||||
| `static/locales/fr.json` | French translations |
|
||||
| `static/locales/de.json` | German translations |
|
||||
| `static/locales/lb.json` | Luxembourgish translations |
|
||||
|
||||
#### Modified Files
|
||||
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| `models/database/vendor.py` | Added language settings columns |
|
||||
| `models/database/user.py` | Added `preferred_language` column |
|
||||
| `models/database/customer.py` | Added `preferred_language` column |
|
||||
| `models/schema/vendor.py` | Added language fields to Pydantic schemas |
|
||||
| `models/schema/auth.py` | Added `preferred_language` to user schemas |
|
||||
| `models/schema/customer.py` | Added `preferred_language` to customer schemas |
|
||||
| `main.py` | Registered LanguageMiddleware |
|
||||
| `app/api/main.py` | Registered language API router |
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Language API (`/api/v1/language`)
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/api/v1/language/set` | POST | Set language preference (cookie) |
|
||||
| `/api/v1/language/current` | GET | Get current language info |
|
||||
| `/api/v1/language/list` | GET | List all available languages |
|
||||
| `/api/v1/language/clear` | DELETE | Clear language preference |
|
||||
|
||||
### Request/Response Examples
|
||||
|
||||
#### Set Language
|
||||
|
||||
```http
|
||||
POST /api/v1/language/set
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"language": "de"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"language": "de",
|
||||
"message": "Language set to Deutsch"
|
||||
}
|
||||
```
|
||||
|
||||
## Translation Files
|
||||
|
||||
Translation files are stored in `static/locales/{lang}.json` with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"common": {
|
||||
"save": "Save",
|
||||
"cancel": "Cancel"
|
||||
},
|
||||
"auth": {
|
||||
"login": "Login",
|
||||
"logout": "Logout"
|
||||
},
|
||||
"nav": {
|
||||
"dashboard": "Dashboard",
|
||||
"products": "Products"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Key Naming Convention
|
||||
|
||||
- Use dot notation for nested keys: `common.save`, `auth.login`
|
||||
- Use snake_case for key names: `product_name`, `order_status`
|
||||
- Group by feature/section: `products.add_product`, `orders.confirm_order`
|
||||
|
||||
## Template Integration
|
||||
|
||||
### Using Translations in Jinja2
|
||||
|
||||
```jinja2
|
||||
{# Import the translation function #}
|
||||
{% from 'shared/macros/language_selector.html' import language_selector %}
|
||||
|
||||
{# Use translation function #}
|
||||
{{ _('common.save') }}
|
||||
|
||||
{# With interpolation #}
|
||||
{{ _('welcome.message', name=user.name) }}
|
||||
|
||||
{# Language selector component #}
|
||||
{{ language_selector(
|
||||
current_language=request.state.language,
|
||||
enabled_languages=vendor.storefront_languages
|
||||
) }}
|
||||
```
|
||||
|
||||
### Request State Variables
|
||||
|
||||
The LanguageMiddleware sets these on `request.state`:
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `language` | str | Resolved language code |
|
||||
| `language_info` | dict | Additional info (source, cookie value, browser value) |
|
||||
|
||||
## Middleware Order
|
||||
|
||||
The LanguageMiddleware must run **after** ContextMiddleware (to know the context type) and **before** ThemeContextMiddleware.
|
||||
|
||||
Execution order (request flow):
|
||||
1. LoggingMiddleware
|
||||
2. VendorContextMiddleware
|
||||
3. ContextMiddleware
|
||||
4. **LanguageMiddleware** <-- Detects language
|
||||
5. ThemeContextMiddleware
|
||||
6. FastAPI Router
|
||||
|
||||
## UI Components
|
||||
|
||||
### Full Language Selector
|
||||
|
||||
```jinja2
|
||||
{{ language_selector(
|
||||
current_language='fr',
|
||||
enabled_languages=['fr', 'de', 'en'],
|
||||
position='right',
|
||||
show_label=true
|
||||
) }}
|
||||
```
|
||||
|
||||
### Compact Selector (Flag Only)
|
||||
|
||||
```jinja2
|
||||
{{ language_selector_compact(
|
||||
current_language='fr',
|
||||
enabled_languages=['fr', 'de', 'en']
|
||||
) }}
|
||||
```
|
||||
|
||||
### Language Settings Form
|
||||
|
||||
For vendor settings pages:
|
||||
|
||||
```jinja2
|
||||
{{ language_settings_form(
|
||||
current_settings={
|
||||
'default_language': vendor.default_language,
|
||||
'dashboard_language': vendor.dashboard_language,
|
||||
'storefront_language': vendor.storefront_language,
|
||||
'storefront_languages': vendor.storefront_languages
|
||||
}
|
||||
) }}
|
||||
```
|
||||
|
||||
## Flag Icons
|
||||
|
||||
The language selector uses [flag-icons](https://flagicons.lipis.dev/) CSS library. Ensure this is included in your base template:
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/flag-icons@7.2.3/css/flag-icons.min.css">
|
||||
```
|
||||
|
||||
Usage: `<span class="fi fi-fr"></span>` for French flag.
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual Testing Checklist
|
||||
|
||||
- [ ] Language cookie is set when selecting language
|
||||
- [ ] Page reloads with correct language after selection
|
||||
- [ ] Vendor dashboard respects user's preferred_language
|
||||
- [ ] Storefront respects customer's preferred_language
|
||||
- [ ] Browser language detection works (clear cookie, use browser with different language)
|
||||
- [ ] Fallback to default language works for unsupported languages
|
||||
- [ ] Language selector shows only enabled languages on storefront
|
||||
|
||||
### API Testing
|
||||
|
||||
```bash
|
||||
# Set language
|
||||
curl -X POST http://localhost:8000/api/v1/language/set \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"language": "de"}'
|
||||
|
||||
# Get current language
|
||||
curl http://localhost:8000/api/v1/language/current
|
||||
|
||||
# List languages
|
||||
curl http://localhost:8000/api/v1/language/list
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Admin Language Support**: Currently admin is English-only. The system is designed to easily add admin language support later.
|
||||
|
||||
2. **Translation Management UI**: Add a UI for vendors to manage their own translations (product descriptions, category names, etc.).
|
||||
|
||||
3. **RTL Language Support**: The `is_rtl_language()` function is ready for future RTL language support (Arabic, Hebrew, etc.).
|
||||
|
||||
4. **Auto-Translation**: Integration with translation APIs for automatic content translation.
|
||||
|
||||
## Rollback
|
||||
|
||||
To rollback this migration:
|
||||
|
||||
```bash
|
||||
alembic downgrade -1
|
||||
```
|
||||
|
||||
This will remove:
|
||||
- `default_language`, `dashboard_language`, `storefront_language`, `storefront_languages` from `vendors`
|
||||
- `preferred_language` from `users`
|
||||
- `preferred_language` from `customers`
|
||||
@@ -1,17 +1,118 @@
|
||||
|
||||
# Letzshop Development Documentation
|
||||
# Letzshop Marketplace Integration
|
||||
|
||||
## Introduction
|
||||
|
||||
Welcome to the Letzshop Development page. Here you’ll find details on:
|
||||
This guide covers the Wizamart platform's integration with the Letzshop marketplace, including:
|
||||
|
||||
- GraphQL API
|
||||
- Authentication
|
||||
- Playground
|
||||
- Deprecations
|
||||
- Order management
|
||||
- Event system
|
||||
- Data structures [1](https://letzshop.lu/en/dev)
|
||||
- **Product Export**: Generate Letzshop-compatible CSV files from your product catalog
|
||||
- **Order Import**: Fetch and manage orders from Letzshop
|
||||
- **Fulfillment Sync**: Confirm/reject orders, set tracking numbers
|
||||
- **GraphQL API Reference**: Direct API access for advanced use cases
|
||||
|
||||
---
|
||||
|
||||
## Product Export
|
||||
|
||||
### Overview
|
||||
|
||||
The Wizamart platform can export your products to Letzshop-compatible CSV format (Google Shopping feed format). This allows you to:
|
||||
|
||||
- Upload your product catalog to Letzshop marketplace
|
||||
- Generate feeds in multiple languages (English, French, German)
|
||||
- Include all required Letzshop fields automatically
|
||||
|
||||
### API Endpoints
|
||||
|
||||
#### Vendor Export
|
||||
|
||||
```http
|
||||
GET /api/v1/vendor/letzshop/export?language=fr
|
||||
Authorization: Bearer <vendor_token>
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `language` | string | `en` | Language for title/description (`en`, `fr`, `de`) |
|
||||
| `include_inactive` | bool | `false` | Include inactive products |
|
||||
|
||||
**Response:** CSV file download (`vendor_code_letzshop_export.csv`)
|
||||
|
||||
#### Admin Export
|
||||
|
||||
```http
|
||||
GET /api/v1/admin/letzshop/export?vendor_id=1&language=fr
|
||||
Authorization: Bearer <admin_token>
|
||||
```
|
||||
|
||||
**Additional Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `vendor_id` | int | Required. Vendor ID to export |
|
||||
|
||||
### CSV Format
|
||||
|
||||
The export generates a tab-separated CSV file with these columns:
|
||||
|
||||
| Column | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `id` | Product SKU | `PROD-001` |
|
||||
| `title` | Product title (localized) | `Wireless Headphones` |
|
||||
| `description` | Product description (localized) | `High-quality...` |
|
||||
| `link` | Product URL | `https://shop.example.com/product/123` |
|
||||
| `image_link` | Main product image | `https://cdn.example.com/img.jpg` |
|
||||
| `additional_image_link` | Additional images (comma-separated) | `img2.jpg,img3.jpg` |
|
||||
| `availability` | Stock status | `in stock` / `out of stock` |
|
||||
| `price` | Regular price with currency | `49.99 EUR` |
|
||||
| `sale_price` | Sale price with currency | `39.99 EUR` |
|
||||
| `brand` | Brand name | `TechBrand` |
|
||||
| `gtin` | Global Trade Item Number | `0012345678901` |
|
||||
| `mpn` | Manufacturer Part Number | `TB-WH-001` |
|
||||
| `google_product_category` | Google category ID | `Electronics > Audio` |
|
||||
| `condition` | Product condition | `new` / `used` / `refurbished` |
|
||||
| `atalanda:tax_rate` | Luxembourg VAT rate | `17` |
|
||||
|
||||
### Multi-Language Support
|
||||
|
||||
Products are exported with localized content based on the `language` parameter:
|
||||
|
||||
```bash
|
||||
# French export
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.example.com/api/v1/vendor/letzshop/export?language=fr"
|
||||
|
||||
# German export
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.example.com/api/v1/vendor/letzshop/export?language=de"
|
||||
|
||||
# English export (default)
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.example.com/api/v1/vendor/letzshop/export?language=en"
|
||||
```
|
||||
|
||||
If a translation is not available for the requested language, the system falls back to English, then to any available translation.
|
||||
|
||||
### Using the Export
|
||||
|
||||
1. **Navigate to Letzshop** in your vendor dashboard
|
||||
2. **Click the Export tab**
|
||||
3. **Select your language** (French, German, or English)
|
||||
4. **Click "Download CSV"**
|
||||
5. **Upload to Letzshop** via their merchant portal
|
||||
|
||||
---
|
||||
|
||||
## Order Integration
|
||||
|
||||
For details on order import and fulfillment, see [Letzshop Order Integration](./letzshop-order-integration.md).
|
||||
|
||||
---
|
||||
|
||||
## Letzshop GraphQL API Reference
|
||||
|
||||
The following sections document the Letzshop GraphQL API for direct integration.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user