WinterCMS research

docs/research/wintercms/quotifypro-15-i18n-locale-detection/15-01-SUMMARY.md

@@ -0,0 +1,103 @@
+---
+phase: 15-locale-detection-routing
+plan: 01
+subsystem: i18n
+tags: [locale, cookie, middleware, wintercms-extension, browser-detection]
+
+# Dependency graph
+requires:
+  - phase: 11-translation-infrastructure
+    provides: Translate plugin with LocaleMiddleware and browser detection config
+provides:
+  - LocalePicker extension setting manual selection cookie
+  - Database sync of user locale preference on switch
+  - URL prefix cookie setting in routes.php
+affects: [16-content-localization, 17-i18n-testing]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [WinterCMS component extension in Plugin boot(), Cookie queue pattern]
+
+key-files:
+  created: []
+  modified:
+    - plugins/golem15/quotify/Plugin.php
+    - plugins/golem15/translate/routes.php
+
+key-decisions:
+  - "Use WinterCMS extension pattern (no modification to core Translate plugin classes)"
+  - "Cookie name from config: golem15.translate::browserDetection.manualSelectionCookie"
+  - "1-year cookie expiry (525600 minutes) from config"
+
+patterns-established:
+  - "LocalePicker extension: Use component.beforeRunAjaxHandler event for pre-handler logic"
+  - "Cookie setting: Use \\Cookie::queue() with config-based name and expiry"
+
+# Metrics
+duration: 2min
+completed: 2026-02-02
+---
+
+# Phase 15 Plan 01: Locale Preference Infrastructure Summary
+
+**LocalePicker extension with manual selection cookie (1-year) and user DB sync, plus URL prefix cookie setting in routes.php**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-02-02T01:01:04Z
+- **Completed:** 2026-02-02T01:02:55Z
+- **Tasks:** 3
+- **Files modified:** 2
+
+## Accomplishments
+
+- LocalePicker component extended to set `locale_manually_set` cookie on manual language switch
+- Logged-in users' locale preference saved to database (`preferred_locale` field) on switch
+- URL prefix visits (/pl/, /de/) now set manual selection cookie preventing browser detection override
+- Verified LocaleMiddleware reads the same cookie name correctly
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Extend LocalePicker to set cookie and sync user preference** - `4a04780` (feat) [quotify submodule]
+2. **Task 2: Set cookie on URL prefix detection in routes.php** - `c389de1` (feat) [translate submodule]
+3. **Task 3: Verify middleware reads the cookie correctly** - verification only, no commit required
+
+**Submodule update:** `382b7a6` (chore: update submodule references)
+
+## Files Created/Modified
+
+- `plugins/golem15/quotify/Plugin.php` - Added extendLocalePicker() method with Cookie::queue and Auth user sync
+- `plugins/golem15/translate/routes.php` - Added cookie setting after loadLocaleFromRequest() succeeds
+
+## Decisions Made
+
+- **WinterCMS extension pattern:** Extended LocalePicker component in Quotify Plugin.php rather than modifying core Translate plugin classes (preserves plugin isolation)
+- **Config-driven cookie settings:** Used `golem15.translate::browserDetection.manualSelectionCookie` and `manualSelectionExpiry` config values for consistency across all cookie operations
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None - all tasks completed successfully.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- Locale preference infrastructure complete
+- Manual selections now persist via cookie (1-year expiry)
+- Logged-in users' preferences sync to database
+- Browser detection correctly skipped when manual selection cookie present
+- Ready for Phase 15 Plan 02 (if any) or Phase 16 (Content Localization)
+
+---
+*Phase: 15-locale-detection-routing*
+*Completed: 2026-02-02*