forked from baron/baron-sso
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
# 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`
|