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="">属性をロケール変更時に同期しなければなりません。- 既に読み込み済みのロケールを重複リクエストしないようキャッシュロジックを実装しなければなりません。