klaus/sodalive-vuejs-creator-admin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
8e8cfa68b3966a513f607bf3a777cd669f9009ab
sodalive-vuejs-creator-admin/docs/20260508_국제화도입.md

12 KiB
Raw Blame History

국제화(i18n) 도입 계획

목표

  • Vue 2 + Vuetify 2 기반에서 한국어(ko), 영어(en), 일본어(ja) 3개 언어를 지원한다.
  • 브라우저 설정을 기본 로케일로 사용하되, 사용자가 선택한 언어가 있으면(localStorage) 그 값을 우선한다.

체크리스트

  • vue-i18n v8 도입 및 기본 설정(src/i18n/index.js)
  • 리소스 파일 생성(src/locales/ko.json, src/locales/en.json, src/locales/ja.json)
  • Vuetify 언어팩 연동(src/plugins/vuetify.js) 및 초기 로케일 동기화
  • main.js에서 vue-i18n ↔ Vuetify 로케일 동기화 로직 추가
  • 공통 컴포넌트 문자열 치환(네비/레이아웃/다이얼로그)
    • src/components/SideMenu.vue 로그아웃/에러/기본 메뉴 텍스트 치환
    • src/App.vue 앱바 타이틀 치환 및 언어 드롭다운 추가
  • 주요 뷰(views/Agent/*) 1차 치환
  • 날짜/숫자/통화 포맷 정책 적용(ja: JPY 소수점 미사용 등)
  • 하드코딩 탐지/미번역 키 점검(정규식 스캔 + missing 핸들러)
  • 언어 전환 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차로 순차 치환 예정