# Phase 15: Locale Detection & Routing - Context

**Gathered:** 2026-02-02
**Status:** Ready for planning

<domain>
## Phase Boundary

Enable users to browse the site in their preferred language through URL prefixes (/pl/, /de/) with automatic browser detection and persistent preference. Build on existing Golem15\Translate plugin infrastructure (LocalePicker, LocaleMiddleware, Translator).

</domain>

<decisions>
## Implementation Decisions

### URL structure
- Use WinterCMS standard pattern: visiting `/pl/about` switches locale to Polish, then all subsequent navigation uses normal URLs without prefix (locale persists via session)
- Default locale (English) is prefix-free: `/jobs` not `/en/jobs`
- Config: `prefixDefaultLocale: false` for cleaner default language URLs
- When URL contains explicit locale prefix, set `locale_manually_set` cookie (same as language picker does)
- Automatic hreflang tags via AlternateHrefLangElements component in all layouts

### Detection behavior
- Browser detection via Accept-Language header on FIRST VISIT ONLY
- Once user has session/cookie, never auto-detect again
- Primary language matching: `de-DE` → `de`, `pl-PL` → `pl` (extract first 2 chars)
- Priority cascade (already in middleware): URL → User DB preference → Session → Browser detection → Default
- Logged-in user's `preferred_locale` from DB always wins over session/browser (but URL prefix still overrides for that request)

### Language switcher UX
- Location: Header, near user menu (top right)
- Style: Dropdown with full text ("English ▼")
- Language names in native form: "Polski", "Deutsch", "English"
- Switching preserves current page (stay on `/jobs/123`, just change language)
- LocalePicker component with `forceUrl: false` (standard pattern)

### Preference persistence
- Guest users: 1-year cookie for locale preference
- Language picker usage saves to DB for logged-in users (auto-update `preferred_locale`)
- URL prefix visit does NOT update DB preference (only affects session)
- Users set their preferred locale during onboarding (already captured in profile)
- Preferred locale dropdown in user profile settings (Profile section, not Family Settings)

### Language suggestion banner
- Show non-intrusive banner when: browser language differs from current page locale AND user hasn't manually selected
- Example: German browser visits `/pl/jobs` from shared link → show "Diese Seite ist auf Deutsch verfügbar" banner
- Dismissing banner sets 1-week cookie, don't show again until expires
- Only show once per session even without explicit dismissal

### Claude's Discretion
- Exact banner styling and positioning
- Cookie names and implementation details
- Component registration and partial structure
- Mobile responsiveness of language switcher

</decisions>

<specifics>
## Specific Ideas

- "I loved WinterCMS approach" — locale switching via URL prefix, then normal navigation without prefixes
- Must be fully compatible with existing Translate and User plugins — no breaking changes
- Language picker behavior should match URL prefix behavior (both set manual-selection cookie)

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 15-locale-detection-routing*
*Context gathered: 2026-02-02*