# userfront locale 전환 문제 분석 및 대응

## 증상
- URL은 `/ko` ↔ `/en`으로 변경되지만 실제 텍스트가 바뀌지 않음.
- 브라우저에서 `window.localStorage.getItem('locale')`가 계속 `null`.
- 빌드/배포 후에도 동일 증상 유지.

## 현재 구조 요약
- Flutter Web + `easy_localization` 사용.
- 경로 기반 로케일: `/:locale` 라우트 + `LocaleGate`로 로케일 적용.
- 번역 리소스: `userfront/assets/translations/*.toml`.
- 로케일 저장: `localStorage` key `locale`.

## 이미 적용한 변경
- `easy_localization` + TOML loader 적용.
- `LocaleGate`에서 로케일 적용 및 저장.
- `LanguageSelector`에서 로케일 저장 + URL 변경.
- `userfront/assets/translations`에 `en.toml`, `ko.toml`, `template.toml` 포함.
- `pubspec.yaml` assets 등록.
- GoRouter 호환성 수정(빌드 오류 대응).

## 원인 후보(우선순위)
1) **로케일 저장이 실제로 실행되지 않음**
   - `LanguageSelector` 클릭 이벤트가 동작하지 않거나,
   - `LocaleGate`가 호출되지 않는 라우트 진입(예: 라우트 변경 없이 SPA 상태만 변경).

2) **서비스 워커/캐시로 인해 구 번들이 계속 로드됨**
   - Flutter Web 기본 `flutter_service_worker.js`가 캐시를 고정.
   - 기존 번들이 남아 `LocaleStorage.write()` 반영 전 코드가 계속 실행될 가능성.

3) **번역 리소스 미로딩**
   - `assets/translations/en.toml`, `ko.toml` 요청이 404 또는 미요청.
   - Nginx 경로/정적 파일 설정에서 `assets/`가 누락된 경우.

4) **en.toml 키 누락으로 fallback 문자열이 표시됨**
   - UI에서 `tr(..., fallback: '한국어')`를 쓰는 경우,
     en.toml에 키가 없으면 한국어가 그대로 노출됨.

## 확인 방법(권장 순서)
1) **로케일 저장 확인**
   - 언어 변경 후 콘솔:
     - `window.localStorage.getItem('locale')`
   - `null`이면 저장 로직 실행 실패.

2) **번역 리소스 요청 확인**
   - DevTools Network에서:
     - `/assets/translations/ko.toml`
     - `/assets/translations/en.toml`
   - 404 또는 미요청이면 assets 로딩 문제.

3) **로케일 반영 확인**
   - UI 내 임시 텍스트로 `context.locale.languageCode` 출력
   - 로케일이 바뀌는데 텍스트가 그대로면 TOML 키 누락 가능성.

4) **캐시 무효화**
   - 하드 리로드(Shift+Reload)
   - service worker 제거 후 재접속

## 현재까지 실행한 대응
- `LocaleGate`에서 로케일 동일 여부와 상관없이 `LocaleStorage.write()`가 실행되도록 수정.
- 라우터 로케일 파싱/전환 로직 보강.
- 번역 리소스 파일 배치 및 assets 등록.

## 앞으로의 대응 계획
1) **서비스 워커 캐시 무효화 전략**
   - `flutter_service_worker.js` 버전 갱신 또는 Nginx 캐시 무력화 정책 적용.
   - 배포 시 `index.html`/`flutter_service_worker.js` 캐시 제어 헤더 추가.

2) **번역 파일 누락 방지**
   - `scripts/sync_userfront_locales.sh`를 CI에서 자동 실행.
   - en/ko 키 누락 검증 테스트 추가.

3) **로케일 저장 검증**
   - 언어 변경 후 `localStorage`에 값이 반드시 들어오는지 E2E 체크 추가.

4) **fallback 사용 최소화**
   - userfront에서 `fallback` 문자열(한국어) 남용 구간 정리.
   - en.toml에 키가 없을 때 한국어가 보이는 현상 방지.

## 참고 파일
- `userfront/lib/core/i18n/locale_gate.dart`
- `userfront/lib/core/widgets/language_selector.dart`
- `userfront/lib/core/i18n/locale_storage_web.dart`
- `userfront/lib/core/i18n/toml_asset_loader.dart`
- `userfront/assets/translations/en.toml`
- `userfront/assets/translations/ko.toml`