baron-sso/docs/trouble-shooting/userfront-locale.md

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