vue-i18n 설정
22.1.1. 플러그인 설정
다국어 지원을 위해 vue-i18n을 사용해야 합니다. 애플리케이션 진입점에서 플러그인을 등록합니다.
typescript
// src/i18n/index.ts
import { createI18n } from 'vue-i18n'
import ko from '@/locales/ko/common.json'
const i18n = createI18n({
legacy: false,
locale: 'ko',
fallbackLocale: 'en',
messages: { ko },
})
export default i18ntypescript
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n'
createApp(App).use(i18n).mount('#app')legacy: false를 설정하여 Composition API 기반의 모드를 사용해야 합니다.- 글로벌 모드(
globalInjection: true)를 사용하여 모든 컴포넌트에서$t(),$d(),$n()헬퍼에 접근할 수 있도록 해야 합니다. - i18n 인스턴스는 별도 파일(
src/i18n/index.ts)로 분리하여 관리해야 합니다.
22.1.2. 로케일 구성
지원 로케일은 다음과 같이 설정합니다.
| 항목 | 값 | 설명 |
|---|---|---|
| 기본 로케일 | ko | 한국어를 기본 언어로 사용 |
| fallback 로케일 | en | 번역 키 누락 시 영어로 대체 |
| 지원 로케일 목록 | ko, en, ja | 프로젝트에서 지원하는 전체 언어 |
typescript
// src/i18n/config.ts
export const SUPPORTED_LOCALES = ['ko', 'en', 'ja'] as const
export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number]
export const DEFAULT_LOCALE: SupportedLocale = 'ko'
export const FALLBACK_LOCALE: SupportedLocale = 'en'- 지원 로케일 목록은 상수로 정의하고, 타입으로 관리해야 합니다.
- 사용자의 브라우저 언어 설정(
navigator.language)을 감지하여 초기 로케일을 결정하는 것을 권장합니다. - 사용자가 선택한 로케일은
localStorage에 저장하여 재방문 시 유지해야 합니다.
22.1.3. fallback 전략
번역 키가 현재 로케일에 존재하지 않을 때의 동작을 명확히 정의해야 합니다.
typescript
const i18n = createI18n({
legacy: false, locale: 'ko',
fallbackLocale: { ja: ['en'], default: ['en'] },
silentFallbackWarn: true, silentTranslationWarn: false,
})fallbackLocale을 반드시 설정해야 합니다. 번역 키 누락 시 빈 문자열이 표시되는 것을 방지합니다.silentFallbackWarn: true를 설정하여 fallback 발생 시 콘솔 경고를 억제하는 것을 권장합니다.silentTranslationWarn: false를 유지하여 번역 키 자체가 누락된 경우에는 경고가 표시되도록 해야 합니다.- 개발 환경에서는 누락된 번역 키를 수집하여 보고서를 생성하는 것을 권장합니다.
- 프로덕션 환경에서는 누락 키 경고가 사용자에게 노출되지 않도록 해야 합니다.
22.1.4. 지연 로딩
초기 번들 크기를 줄이기 위해 로케일 파일을 동적으로 로딩해야 합니다.
typescript
// src/i18n/loader.ts
import type { I18n } from 'vue-i18n'
import type { SupportedLocale } from './config'
const loadedLocales = new Set<SupportedLocale>(['ko'])
export async function setLocale(i18n: I18n, locale: SupportedLocale): Promise<void> {
if (!loadedLocales.has(locale)) {
const messages = await import(`@/locales/${locale}/common.json`)
i18n.global.setLocaleMessage(locale, messages.default)
loadedLocales.add(locale)
}
i18n.global.locale.value = locale
document.documentElement.setAttribute('lang', locale)
localStorage.setItem('locale', locale)
}- 기본 로케일(
ko)만 초기 번들에 포함하고, 나머지 로케일은 필요 시 동적으로 로딩해야 합니다. - 언어 변경 시 비동기로 로케일 파일을 로드하고, 로드 완료 후 로케일을 전환해야 합니다.
- 로케일 전환 중 로딩 상태를 사용자에게 표시하는 것을 권장합니다.
<html lang="">속성을 로케일 변경 시 동기화해야 합니다.- 이미 로드된 로케일은 중복 요청하지 않도록 캐싱 로직을 구현해야 합니다.