vue-i18n Configuration
22.1.1. Plugin Configuration
vue-i18n must be used for internationalization support. Register the plugin at the application entry point.
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: falsemust be set to use Composition API-based mode.- Global mode (
globalInjection: true) must be used so that$t(),$d(), and$n()helpers are accessible in all components. - The i18n instance must be separated into its own file (
src/i18n/index.ts) for management.
22.1.2. Locale Configuration
Supported locales must be configured as follows.
| Item | Value | Description |
|---|---|---|
| Default Locale | ko | Korean is used as the default language |
| Fallback Locale | en | Falls back to English when a translation key is missing |
| Supported Locale List | ko, en, ja | All languages supported by the project |
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'- The supported locale list must be defined as constants and managed through types.
- Detecting the user's browser language setting (
navigator.language) to determine the initial locale is recommended. - The user's selected locale must be saved to
localStorageand persisted across revisits.
22.1.3. Fallback Strategy
The behavior when a translation key does not exist in the current locale must be clearly defined.
typescript
const i18n = createI18n({
legacy: false, locale: 'ko',
fallbackLocale: { ja: ['en'], default: ['en'] },
silentFallbackWarn: true, silentTranslationWarn: false,
})fallbackLocalemust be configured. This prevents empty strings from being displayed when translation keys are missing.- Setting
silentFallbackWarn: trueto suppress console warnings on fallback is recommended. silentTranslationWarn: falsemust be maintained so that warnings are displayed when translation keys themselves are missing.- Collecting missing translation keys in the development environment and generating reports is recommended.
- Missing key warnings must not be exposed to users in the production environment.
22.1.4. Lazy Loading
Locale files must be dynamically loaded to reduce the initial bundle size.
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)
}- Only the default locale (
ko) must be included in the initial bundle; all other locales must be dynamically loaded on demand. - When the language is changed, the locale file must be loaded asynchronously, and the locale must be switched after loading completes.
- Displaying a loading state to the user during locale switching is recommended.
- The
<html lang="">attribute must be synchronized when the locale changes. - Caching logic must be implemented to prevent duplicate requests for already-loaded locales.