# Phase Handover — Experience 11.5 Localization, RTL/LTR & Media

## Metadata

| Field | Value |
| --- | --- |
| Phase ID | `experience-11.5` |
| Title | Localization, RTL/LTR & Media |
| Status | Complete |
| Service(s) | `experience` (`experience_db`) |
| Version | `0.11.5.0` |
| Date | 2026-07-26 |
| ADR(s) | [ADR-016](../architecture/adr/ADR-016.md), [ADR-008](../architecture/adr/ADR-008.md) |

## Discovery Summary

Phase 11.4 delivered the template catalog/instantiation pipeline. Foundation locale profiles (11.0) already described language + direction catalogs, and themes expose `DirectionMode` shells, but tenants could not bind locales to sites, store multi-locale content shells, or attach media without risking binaries in `experience_db`. This phase adds site locale bindings, localization upserts with first-class RTL/LTR, and media refs that store Storage file references only.

## Reusable Components

| Component | Location | Reuse notes |
| --- | --- | --- |
| Site locale binding | `app/models/localization.py` (`SiteLocaleBinding`), `app/services/localization.py` | One default locale per site; direction inherited from profile or overridden |
| Localization shells | `ExperienceLocalization` | Unique per tenant/target/locale; upsert API |
| Media refs | `ExperienceMediaRef` | `storage_file_ref` only; validators reject `data:` / base64 metadata keys |
| Policies / specs | `app/policies/localization.py`, `app/specifications/localization.py` | Profile usability, status transitions, list UX |
| Validators | `app/validators/localization.py` | Locale code, text direction, storage ref, no-binary payload |

## Public APIs

| Method | Path | Permission |
| --- | --- | --- |
| CRUD | `/api/v1/site-locale-bindings` | `experience.locales.*` |
| Upsert + CRUD | `/api/v1/localizations` | `experience.locales.*` |
| CRUD | `/api/v1/media-refs` | `experience.media_refs.*` |

## Events

| Event type | Notes |
| --- | --- |
| `experience.site_locale.*` | assigned / updated / replaced / unassigned |
| `experience.localization.*` | upserted / updated / archived |
| `experience.media_ref.*` | created / updated / archived |

## Extension Points

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| `ExperienceLocalization.content_json` | Locale-specific content shells for renderers | Store binary media or form submission payloads |
| `ExperienceMediaRef.storage_file_ref` | Point at File Storage objects | Inline blobs, data-URIs, base64 in metadata |
| `SiteLocaleBinding.text_direction` | Concrete rtl/ltr for site rendering | Do not invent a second locale catalog — reuse locale profiles |

## Known Limitations

- No forms/surveys/appointment engine (11.6)
- No SEO/PWA publishing pipeline (11.7)
- Media refs do not call StorageProvider at write time (ref validation only); resolve-on-read remains a later integration concern
- Localization targets are shells — deep CMS field graphs remain out of scope

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | `0006_phase_115_localization_media` (head) |
| Upgrade steps | `alembic upgrade head` |
| Downgrade support | Drops `experience_media_refs`, `experience_localizations`, `experience_site_locale_bindings` |
| Breaking changes | None (additive) |

## Dependencies

| Dependency | Type |
| --- | --- |
| experience-11.4 templates | Required prior (manifest chain) |
| experience-11.1 sites/pages | Required (bindings/localizations attach to sites/pages) |
| experience-11.0 locale profiles | Required (site bindings reference profiles) |
| File Storage (API contract) | External — media binaries never in `experience_db` |
| ADR-016 | Boundaries |

## Quality Gates

- [x] Discovery complete
- [x] Architecture / boundaries preserved
- [x] Tests green
- [x] Permissions / events registered
- [x] Docs + manifests + next-steps updated
- [x] Phase handover written

## Next Phase Entry

| Field | Value |
| --- | --- |
| Next phase | `experience-11.6` — Forms, Surveys & Appointments |
| Entry docs | This handover + [experience-phase-11-5.md](../experience-phase-11-5.md) |
| Do not start | Forms before localization/media DoD is green (this phase) |