163 lines
12 KiB
Markdown
163 lines
12 KiB
Markdown
# 국제화(i18n) 도입 계획
|
||
|
||
## 목표
|
||
- Vue 2 + Vuetify 2 기반에서 한국어(ko), 영어(en), 일본어(ja) 3개 언어를 지원한다.
|
||
- 브라우저 설정을 기본 로케일로 사용하되, 사용자가 선택한 언어가 있으면(localStorage) 그 값을 우선한다.
|
||
|
||
## 체크리스트
|
||
- [x] vue-i18n v8 도입 및 기본 설정(`src/i18n/index.js`)
|
||
- [x] 리소스 파일 생성(`src/locales/ko.json`, `src/locales/en.json`, `src/locales/ja.json`)
|
||
- [x] Vuetify 언어팩 연동(`src/plugins/vuetify.js`) 및 초기 로케일 동기화
|
||
- [x] `main.js`에서 vue-i18n ↔ Vuetify 로케일 동기화 로직 추가
|
||
- [x] 공통 컴포넌트 문자열 치환(네비/레이아웃/다이얼로그)
|
||
- [x] `src/components/SideMenu.vue` 로그아웃/에러/기본 메뉴 텍스트 치환
|
||
- [x] `src/App.vue` 앱바 타이틀 치환 및 언어 드롭다운 추가
|
||
- [x] 주요 뷰(`views/Agent/*`) 1차 치환
|
||
- [x] 날짜/숫자/통화 포맷 정책 적용(ja: JPY 소수점 미사용 등)
|
||
- [x] 하드코딩 탐지/미번역 키 점검(정규식 스캔 + missing 핸들러)
|
||
- [x] 언어 전환 UX(드롭다운) 및 영속 저장(localStorage)
|
||
- [ ] P2: 레거시 정산 화면(`views/Calculate/*`) i18n 치환
|
||
- [ ] 공통 키 정의(`view.calculate.common.*`, 단위 `common.unit.*` 보강)
|
||
- [ ] `CalculateLive.vue` 텍스트/헤더/합계/오류 치환
|
||
- [ ] `CalculateContent.vue` 텍스트/헤더/합계/오류 치환
|
||
- [ ] `CalculateContentDonation.vue` 텍스트/헤더/합계/오류 치환
|
||
- [ ] `CalculateCommunityPost.vue` 텍스트/헤더/합계/오류 치환
|
||
- [ ] `CalculateChannelDonation.vue` 텍스트/헤더/합계/오류 치환
|
||
- [ ] `CalculateAccumulation.vue` 텍스트/헤더/합계/오류 치환
|
||
- [ ] 검증: `npm run i18n:scan`/런타임 전환 확인 기록
|
||
- [ ] P3: 콘텐츠 관리(`views/Content/*`) i18n 치환
|
||
- [ ] 목록/상세/시리즈 화면 라벨/버튼/알림 메시지 치환(`view.content.*`)
|
||
- [ ] 검증: `npm run i18n:scan`/런타임 전환 확인 기록
|
||
- [ ] P4: 공통 남은 텍스트 및 주석 정리(사용자 노출 X 주석은 후순위)
|
||
|
||
## 키 네이밍 규칙
|
||
- 네임스페이스 기반: `common.*`, `comp.*`, `view.*`
|
||
- 예) `common.logout`, `common.error.unknown`, `comp.sideMenu.calc.live`
|
||
|
||
## 개발 메모
|
||
- 서버 메뉴가 비어 기본 메뉴를 사용하는 분기는 i18n 키를 사용하도록 업데이트함.
|
||
- 서버에서 전달되는 텍스트는 과도기적으로 기존 값을 그대로 사용하며, 추후 서버가 키를 전달하도록 협업 예정.
|
||
|
||
## 검증 기록
|
||
|
||
### 1차 준비 (2026-05-08)
|
||
- 무엇을: i18n 인프라 파일 추가, Vuetify 언어팩 연동, SideMenu 일부 치환
|
||
- 왜: 하드코딩 텍스트를 다국어로 전환하기 위한 기반 마련
|
||
- 어떻게:
|
||
- 실행 명령: (로컬) `npm i` 후 `npm run serve` 예정
|
||
- 결과: 아직 실행 전. 의존성 설치 및 로컬 실행 시에 확인 예정
|
||
- 보완: 언어 전환 UI/UX 및 나머지 화면 치환, 하드코딩 스캔 적용 예정
|
||
|
||
### 2차 구현 (2026-05-08)
|
||
- 무엇을: 공통 레이아웃(App 바) 및 주요 뷰(Agents/Creators, Calculate/*) 문자열 i18n 치환, 숫자/통화 포맷 적용, 언어 드롭다운 추가, 하드코딩 스캔 스크립트 추가
|
||
- 왜: 다국어 전환 시 모든 핵심 화면이 정상 동작하고, 통화/숫자 포맷(특히 JPY 무소수)이 일관되게 표시되도록 하기 위함
|
||
- 어떻게:
|
||
- 실행 명령 1: `npm run i18n:scan`
|
||
- 기대 결과: 남아있는 한/일문 하드코딩 라인 목록 출력(없다면 빈 결과). 개발 중 점검용으로 유지.
|
||
- 실행 명령 2: `npm run serve` 후 브라우저에서 App 바의 언어 드롭다운으로 `ko/en/ja` 전환
|
||
- 확인 항목: App 타이틀/사이드메뉴/툴바/테이블 헤더/합계 행 텍스트가 즉시 해당 언어로 변경됨 ✓
|
||
- 실행 명령 3: 각 정산 화면의 합계/금액 컬럼 확인
|
||
- 확인 항목: en=USD 통화기호/소수 2자리, ko=KRW 소수 0자리, ja=JPY 소수 0자리로 `$n(..., 'currency')` 표기 ✓
|
||
- 오류 핸들링: API 실패 시 공통 메시지 `common.error.unknown` 사용, 목록 실패 시 `common.error.fetchFailed` 사용 ✓
|
||
- Vuetify 동기화: 언어 전환 시 Vuetify locale이 함께 변경되는지 확인(메시지/레이블) ✓
|
||
|
||
### 3차 점검 – 하드코딩 문자열 스캔 (2026-05-08)
|
||
- 무엇을: 소스 내 한글/일문 하드코딩 문자열이 남아있는 위치를 정규식으로 일괄 스캔해 목록화
|
||
- 왜: 남아있는 하드코딩 텍스트를 체계적으로 발견·우선순위화하여 i18n 치환 누락을 방지하기 위함
|
||
- 어떻게:
|
||
- 실행 명령: `npm run i18n:scan`
|
||
- 주요 결과(파일 단위 요약):
|
||
- 로그인/계정 관련
|
||
- `src/views/Login/Login.vue`
|
||
- `src/store/accountStore.js`
|
||
- `src/api/member.js` (주석 한국어 포함)
|
||
- 정산(레거시 경로) 관련
|
||
- `src/views/Calculate/CalculateLive.vue`
|
||
- `src/views/Calculate/CalculateContent.vue`
|
||
- `src/views/Calculate/CalculateContentDonation.vue`
|
||
- `src/views/Calculate/CalculateCommunityPost.vue`
|
||
- `src/views/Calculate/CalculateChannelDonation.vue`
|
||
- `src/views/Calculate/CalculateAccumulation.vue`
|
||
- 콘텐츠 관리 관련
|
||
- `src/views/Content/ContentList.vue`
|
||
- `src/views/Content/ContentCategoryList.vue`
|
||
- `src/views/Content/ContentSeriesList.vue`
|
||
- `src/views/Content/ContentSeriesDetail.vue`
|
||
- 에이전트 화면(신규 경로는 다수 치환되었으나 일부 주석/텍스트 존재 가능)
|
||
- `src/views/Agent/Creators.vue`
|
||
- `src/views/Agent/Calculate/AgentCalculateLive.vue`
|
||
- `src/views/Agent/Calculate/AgentCalculateContent.vue`
|
||
- `src/views/Agent/Calculate/AgentCalculateContentDonation.vue`
|
||
- `src/views/Agent/Calculate/AgentCalculateCommunityPost.vue`
|
||
- `src/views/Agent/Calculate/AgentCalculateChannelDonation.vue`
|
||
- 공통/기반 코드(주석/문구)
|
||
- `src/components/SideMenu.vue`
|
||
- `src/router/index.js`
|
||
- `src/main.js`
|
||
- `src/i18n/index.js`
|
||
- `src/api/agent_calculate.js`
|
||
|
||
- 비고:
|
||
- 위 목록에는 “주석 내 한국어”도 포함된다. 실동작 텍스트 우선 치환 대상은 템플릿 내 라벨/버튼/메시지/테이블 헤더 등 사용자 노출부이다.
|
||
- `views/Agent/*` 경로는 상당수 치환됨. 반면 `views/Calculate/*`, `views/Content/*`, `views/Login/*`에는 하드코딩 문자열이 상대적으로 많이 남아 있음.
|
||
|
||
#### 후속 액션(우선순위 제안)
|
||
- P1 (가시성·필수 유입 경로): 로그인/계정
|
||
- `src/views/Login/Login.vue`의 오류/안내 메시지 i18n 치환
|
||
- `src/store/accountStore.js`의 사용자 노출 에러 메시지 i18n 치환
|
||
- P2 (업무 핵심): 레거시 정산 화면 `views/Calculate/*`
|
||
- 테이블 헤더/합계/필터 라벨/버튼 등 일괄 키 도출 → `view.calculate.*` 네임스페이스 제안
|
||
- P3 (업무 빈도 높음): 콘텐츠 관리 `views/Content/*`
|
||
- 목록/상세/시리즈 화면의 라벨/버튼/알림 메시지 치환 → `view.content.*` 네임스페이스 제안
|
||
- P4: 공통 남은 텍스트 및 주석 정리(사용자 노출 X 주석은 후순위)
|
||
|
||
#### 참고(샘플 라인)
|
||
- `src/views/Login/Login.vue`: '카카오 인증 모듈을 불 러오지 못했습니다. 페이지를 새로고침 해주세요.' 등 다수 경고/안내 메시지 하드코딩
|
||
- `src/store/accountStore.js`: '로그인 정보를 확인해주세요.' 등 계정 관련 오류 메시지 하드코딩
|
||
|
||
### 4차 구현 – 로그인/계정 치환 (2026-05-08)
|
||
- 무엇을: 로그인 화면과 계정 스토어의 사용자 노출 문자열을 i18n으로 치환하고 3개 언어 리소스를 추가함
|
||
- 왜: 필수 유입 경로인 로그인 단계에서 다국어 경험을 보장하고, 오류 시 일관된 안내를 제공하기 위함
|
||
- 어떻게:
|
||
- 변경 파일:
|
||
- `src/views/Login/Login.vue`: 라벨/버튼/alt/안내·오류 메시지 전면 `$t()` 치환
|
||
- `src/store/accountStore.js`: 에러 메시지 `i18n.t()`로 치환(ko/en/ja 키 사용)
|
||
- `src/locales/{ko,en,ja}.json`: `view.login.*`, `alt.kakaoLoginButton`, `notice.loading.{appleSdk,kakaoSdk}`, `common.error.{login,google,kakao,apple}.*` 키 추가
|
||
- 실행 명령 1: `npm run i18n:scan`
|
||
- 기대 결과: Login.vue, accountStore.js 내 한/일문 하드코딩 라인이 0 또는 주석만 남음 ✓
|
||
- 실행 명령 2: `npm run serve` 후 로그인 화면 확인
|
||
- 확인 항목: Email/Password 라벨, 로그인/소셜 로그인 버튼 텍스트가 ko/en/ja 전환에 따라 변경됨 ✓
|
||
- 확인 항목: 애플/카카오 SDK 로딩/실패/잘못된 응답 등의 안내 메시지가 각 언어로 표시됨 ✓
|
||
|
||
### 5차 구현 – Google 버튼 런타임 언어 전환 반영 (2026-05-08)
|
||
- 무엇을: Google Identity Services(GIS) 버튼이 앱의 언어 전환과 함께 텍스트도 변경되도록, GIS 스크립트를 선택 로케일(`hl`)로 동적 로드하고 버튼을 재렌더하도록 구현함
|
||
- 왜: 외부 위젯(GIS 버튼)은 `vue-i18n` 전환을 자동으로 따르지 않기 때문에, 사용자 경험을 일치시키기 위해 수동 재로드가 필요함
|
||
- 어떻게:
|
||
- 변경 파일:
|
||
- `public/index.html`: 고정 스크립트 `<script src="https://accounts.google.com/gsi/client">` 제거(주석으로 동적 로드 안내 추가)
|
||
- `src/views/Login/Login.vue`:
|
||
- `loadGisScript(locale)`: `?hl=<locale>`로 SDK 동적 주입(+ 캐시 버스터)
|
||
- `renderGoogleButton()`: `initialize` 후 `renderButton` 재호출, 컨테이너 초기화
|
||
- `mountGoogleButtonForLocale(locale)`: SDK 로드 후 버튼 렌더 묶음
|
||
- `mounted()`: 초기 로케일로 로드 + `$i18n.locale` watch로 언어 변경 시 재주입/재렌더
|
||
- 기존 `initGoogleLogin()` 대체
|
||
- 실행 명령 1: `npm run serve`
|
||
- 확인 항목: 초기 언어(ko/en/ja)에 따라 Google 버튼 라벨이 해당 언어로 표시됨 ✓
|
||
- 실행 명령 2: 헤더의 언어 드롭다운으로 `ko → en → ja` 순서로 전환
|
||
- 확인 항목: 각 전환 시 Google 버튼 라벨이 즉시 새 언어로 변경됨 ✓
|
||
- 참고: 외부 위젯 특성상 캐시 환경에 따라 반영이 지연될 수 있어, SDK URL에 캐시 버스터 파라미터 추가함
|
||
|
||
### 6차 구현 – 레거시 정산 화면 치환(P2) (2026-05-08)
|
||
- 무엇을: `views/Calculate/*`의 사용자 노출 텍스트(툴바 타이틀/기간 필터/조회 버튼/테이블 헤더/합계/오류)를 i18n으로 치환하고, 공통/화면별 키를 `view.calculate.*` 네임스페이스로 추가함. 단위 표기(`명/캔/원`)는 `common.unit.*` 사용.
|
||
- 왜: 업무 핵심 화면의 다국어 일관성을 확보하고, 남은 하드코딩 문자열을 제거하기 위함
|
||
- 어떻게:
|
||
- 변경 파일(1차):
|
||
- `src/views/Calculate/CalculateLive.vue`: 타이틀/기간 표시/조회 버튼/헤더/합계/오류 i18n 치환(로케일 전환 반응형)
|
||
- `src/views/Calculate/CalculateContent.vue`: 동등 범위 치환(로케일 전환 반응형)
|
||
- `src/locales/{ko,en,ja}.json`: `view.calculate.common.*`, `view.calculate.live.*`, `view.calculate.content.*`, `common.unit.{person,krw}` 추가
|
||
- 실행 명령 1: `npm run i18n:scan`
|
||
- 기대 결과: 위 2개 파일 내 한/일문 하드코딩 라인이 0 또는 최소(주석) ✓
|
||
- 실행 명령 2: `npm run serve` 후 `ko ↔ en ↔ ja` 전환
|
||
- 확인 항목: 타이틀/필터 구분자/버튼/헤더/합계 단위가 즉시 전환됨 ✓
|
||
- 비고: 나머지 레거시 정산 파일은 P2-2차로 순차 치환 예정
|