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>

app/api/main.py

@@ -11,6 +11,7 @@ This module provides:
 from fastapi import APIRouter
 
 from app.api.v1 import admin, shop, vendor
+from app.api.v1.shared import language
 
 api_router = APIRouter()
 
@@ -34,3 +35,10 @@ api_router.include_router(vendor.router, prefix="/v1/vendor", tags=["vendor"])
 # ============================================================================
 
 api_router.include_router(shop.router, prefix="/v1/shop", tags=["shop"])
+
+# ============================================================================
+# SHARED ROUTES (Cross-context utilities)
+# Prefix: /api/v1
+# ============================================================================
+
+api_router.include_router(language.router, prefix="/v1", tags=["language"])

app/api/v1/shared/language.py

@@ -0,0 +1,179 @@
+# app/api/v1/shared/language.py
+"""
+Language API endpoints for setting user/customer language preferences.
+
+These endpoints handle:
+- Setting language preference via cookie
+- Getting current language info
+- Listing available languages
+"""
+import logging
+
+from fastapi import APIRouter, Request, Response
+from pydantic import BaseModel, Field
+
+from app.utils.i18n import (
+    DEFAULT_LANGUAGE,
+    LANGUAGE_FLAGS,
+    LANGUAGE_NAMES,
+    LANGUAGE_NAMES_EN,
+    SUPPORTED_LANGUAGES,
+    get_language_info,
+)
+from middleware.language import LANGUAGE_COOKIE_NAME, set_language_cookie
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/language", tags=["language"])
+
+
+class SetLanguageRequest(BaseModel):
+    """Request body for setting language preference."""
+
+    language: str = Field(
+        ...,
+        description="Language code (en, fr, de, lb)",
+        min_length=2,
+        max_length=5,
+    )
+
+
+class SetLanguageResponse(BaseModel):
+    """Response after setting language preference."""
+
+    success: bool
+    language: str
+    message: str
+
+
+class LanguageInfo(BaseModel):
+    """Information about a single language."""
+
+    code: str
+    name: str
+    name_en: str
+    flag: str
+
+
+class LanguageListResponse(BaseModel):
+    """Response listing all available languages."""
+
+    languages: list[LanguageInfo]
+    current: str
+    default: str
+
+
+class CurrentLanguageResponse(BaseModel):
+    """Response with current language information."""
+
+    code: str
+    name: str
+    name_en: str
+    flag: str
+    source: str  # Where the language was determined from (cookie, browser, default)
+
+
+# public - Language preference can be set without authentication
+@router.post("/set", response_model=SetLanguageResponse)
+async def set_language(
+    request: Request,
+    response: Response,
+    body: SetLanguageRequest,
+) -> SetLanguageResponse:
+    """
+    Set the user's language preference.
+
+    This sets a cookie that will be used for subsequent requests.
+    The page should be reloaded after calling this endpoint.
+    """
+    language = body.language.lower()
+
+    if language not in SUPPORTED_LANGUAGES:
+        return SetLanguageResponse(
+            success=False,
+            language=language,
+            message=f"Unsupported language: {language}. Supported: {', '.join(SUPPORTED_LANGUAGES)}",
+        )
+
+    # Set language cookie
+    set_language_cookie(response, language)
+
+    logger.info(f"Language preference set to: {language}")
+
+    return SetLanguageResponse(
+        success=True,
+        language=language,
+        message=f"Language set to {LANGUAGE_NAMES.get(language, language)}",
+    )
+
+
+@router.get("/current", response_model=CurrentLanguageResponse)
+async def get_current_language(request: Request) -> CurrentLanguageResponse:
+    """
+    Get the current language for this request.
+
+    Returns information about the detected language and where it came from.
+    """
+    # Get language from request state (set by middleware)
+    language = getattr(request.state, "language", DEFAULT_LANGUAGE)
+    language_info = getattr(request.state, "language_info", {})
+
+    # Determine source
+    source = "default"
+    if language_info.get("cookie"):
+        source = "cookie"
+    elif language_info.get("browser"):
+        source = "browser"
+
+    info = get_language_info(language)
+
+    return CurrentLanguageResponse(
+        code=info["code"],
+        name=info["name"],
+        name_en=info["name_en"],
+        flag=info["flag"],
+        source=source,
+    )
+
+
+@router.get("/list", response_model=LanguageListResponse)
+async def list_languages(request: Request) -> LanguageListResponse:
+    """
+    List all available languages.
+
+    Returns all supported languages with their display names.
+    """
+    current = getattr(request.state, "language", DEFAULT_LANGUAGE)
+
+    languages = [
+        LanguageInfo(
+            code=code,
+            name=LANGUAGE_NAMES.get(code, code),
+            name_en=LANGUAGE_NAMES_EN.get(code, code),
+            flag=LANGUAGE_FLAGS.get(code, ""),
+        )
+        for code in SUPPORTED_LANGUAGES
+    ]
+
+    return LanguageListResponse(
+        languages=languages,
+        current=current,
+        default=DEFAULT_LANGUAGE,
+    )
+
+
+# public - Language preference clearing doesn't require authentication
+@router.delete("/clear")
+async def clear_language(response: Response) -> SetLanguageResponse:
+    """
+    Clear the language preference cookie.
+
+    After clearing, the language will be determined from browser settings or defaults.
+    """
+    response.delete_cookie(key=LANGUAGE_COOKIE_NAME)
+
+    return SetLanguageResponse(
+        success=True,
+        language=DEFAULT_LANGUAGE,
+        message="Language preference cleared. Using browser/default language.",
+    )