---
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*