78 lines
3.2 KiB
Markdown
78 lines
3.2 KiB
Markdown
# 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*
|