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, ADR-008 |
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
Next Phase Entry
| Field |
Value |
| Next phase |
experience-11.6 — Forms, Surveys & Appointments |
| Entry docs |
This handover + experience-phase-11-5.md |
| Do not start |
Forms before localization/media DoD is green (this phase) |
203671a7bf