docs(i18n): document CMS template translations and multi-language content pages

Add sections covering CMS locale file structure, translated template
inventory, TranslatableText pattern for sections, and the new
title_translations/content_translations model API with migration cms_002.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/development/migration/language-i18n-implementation.md

@@ -295,19 +295,169 @@ curl http://localhost:8000/api/v1/language/current
 curl http://localhost:8000/api/v1/language/list
 ```
 
+## CMS Template i18n
+
+All platform-facing templates use the `_()` translation function with keys from module-scoped locale files.
+
+### Locale File Structure
+
+CMS locale files are at `app/modules/cms/locales/{en,fr,de,lb}.json` with 340 keys organized as:
+
+```
+platform.nav.*           — Navigation labels
+platform.hero.*          — Default homepage hero section
+platform.pricing.*       — Default homepage pricing section
+platform.features.*      — Default homepage feature labels
+platform.signup.*        — Signup flow
+platform.success.*       — Post-signup success page
+platform.cta.*           — Call-to-action section
+platform.content_page.*  — Content page UI chrome
+platform.footer.*        — Footer labels
+platform.modern.*        — Modern homepage template (~90 keys)
+platform.minimal.*       — Minimal homepage template (17 keys)
+platform.find_shop.*     — Find-your-shop page
+platform.addons.*        — Add-on pricing labels
+messages.*               — Flash/toast messages
+confirmations.*          — Confirmation dialogs
+permissions.*            — Permission labels
+features.*               — Feature gate labels
+menu.*                   — Menu section labels
+```
+
+### Template Usage
+
+```jinja2
+{# Simple key lookup #}
+{{ _("cms.platform.modern.hero_title_1") }}
+
+{# With interpolation #}
+{{ _("cms.platform.modern.cta_trial", trial_days=14) }}
+```
+
+### Translated Templates (Complete)
+
+| Template | Keys Used | Status |
+|----------|-----------|--------|
+| `homepage-default.html` + section partials | `platform.hero.*`, `platform.pricing.*`, etc. | Fully translated |
+| `homepage-modern.html` | `platform.modern.*` (~90 keys) | Fully translated |
+| `homepage-minimal.html` | `platform.minimal.*` (17 keys) | Fully translated |
+| `signup.html` | `platform.signup.*` | Fully translated |
+| `signup-success.html` | `platform.success.*` | Fully translated |
+| `content-page.html` | `platform.content_page.*` | Fully translated |
+| `find-shop.html` | `platform.find_shop.*` | Fully translated |
+| `base.html` | `platform.nav.*`, `platform.footer.*` | Fully translated |
+
+### CMS Section Translations (TranslatableText Pattern)
+
+Homepage sections stored in the `ContentPage.sections` JSON column use the `TranslatableText` pattern:
+
+```json
+{
+  "hero": {
+    "title": {"translations": {"fr": "Bienvenue", "en": "Welcome", "de": "Willkommen", "lb": "Wëllkomm"}}
+  }
+}
+```
+
+Resolution in templates via `_t()` macro:
+
+```jinja2
+{% macro _t(field, fallback='') %}
+{%- if field and field.translations -%}
+    {{ field.translations.get(lang) or field.translations.get(default_lang) or fallback }}
+{%- endif -%}
+{% endmacro %}
+```
+
+## Multi-Language Content Pages
+
+### Migration: `cms_002_add_title_content_translations`
+
+Added two nullable JSON columns to `content_pages`:
+
+```sql
+ALTER TABLE content_pages ADD COLUMN title_translations JSON;
+ALTER TABLE content_pages ADD COLUMN content_translations JSON;
+```
+
+### Data Format
+
+```json
+{
+  "en": "About Us",
+  "fr": "À propos",
+  "de": "Über uns",
+  "lb": "Iwwer eis"
+}
+```
+
+### Model API
+
+```python
+# Get translated title with fallback chain:
+# title_translations[lang] → title_translations[default_lang] → self.title
+page.get_translated_title(lang="de", default_lang="fr")
+
+# Same for content:
+page.get_translated_content(lang="de", default_lang="fr")
+```
+
+### Template Usage
+
+In `content-page.html`:
+
+```jinja2
+{% set _lang = current_language|default('fr') %}
+{% set _page_title = page.get_translated_title(_lang) %}
+{% set _page_content = page.get_translated_content(_lang) %}
+
+<h1>{{ _page_title }}</h1>
+{{ _page_content | safe }}
+```
+
+In `base.html` (nav/footer):
+
+```jinja2
+{{ page.get_translated_title(current_language|default('fr')) }}
+```
+
+### Seed Script
+
+The seed script (`scripts/seed/create_default_content_pages.py`) uses the `tt()` helper:
+
+```python
+def tt(en, fr, de, lb=None):
+    """Build a language-keyed dict for title_translations."""
+    d = {"en": en, "fr": fr, "de": de}
+    if lb: d["lb"] = lb
+    return d
+```
+
+All platform pages, legal pages, and store defaults include `title_translations` with en/fr/de/lb values.
+
 ## 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 stores to manage their own translations (product descriptions, category names, etc.).
+2. **Translation Management UI**: Add a language-tabbed title/content editor to the CMS admin for editing `title_translations` and `content_translations`.
 
 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.
 
+5. **Content Translation**: Translate `content_translations` for platform marketing pages (currently only titles are translated; content remains English-only in the seed data).
+
 ## Rollback
 
-To rollback this migration:
+To rollback the content page translations:
+
+```bash
+alembic downgrade cms_001
+```
+
+This will remove `title_translations` and `content_translations` from `content_pages`.
+
+To rollback the base language settings:
 
 ```bash
 alembic downgrade -1