Skip to main content

Vue i18n：vue-i18n による国際化設定完全ガイド

インストールから本番環境まで。Composition API を使った vue-i18n の設定、CLDR 規則による複数形処理、コンポーネント補間、スマートなロケールフォールバックチェーンを解説します。

1

vue-i18n のインストール

vue-i18n は Vue.js 公式の国際化プラグインです。リアクティブな翻訳、ICU 形式の複数形処理、コンポーネント補間、日時・数値の書式設定を提供し、Options API と Composition API の両方に対応します。

Terminal
npm install vue-i18n@9
2

vue-i18n の設定

createI18n() で i18n インスタンスを作成し、Vue プラグインとして登録します。ロケールメッセージを定義し、デフォルトロケールとフォールバックロケールを設定します。vue-i18n は、legacy（Options API）と composition（Composition API）の両モードに対応します。

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'
import en from './locales/en.json'
import de from './locales/de.json'

const i18n = createI18n({
  legacy: false,           // Use Composition API mode
  locale: 'en',            // Default locale
  fallbackLocale: 'en',   // Fallback locale
  messages: { en, de },
})

export default i18n
src/main.ts
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n'

const app = createApp(App)
app.use(i18n)
app.mount('#app')
「Not available in legacy mode」エラーが表示される場合は、Composition API の i18n 呼び出し（useI18n()）と legacy モード設定が混在しています。Composition API モードを使用するには createI18n() で legacy: false を設定するか、Options API の $t() 構文へ統一してください。
3

テンプレートで翻訳を使用

vue-i18n は、テンプレート用の $t() 関数（Options API）と、useI18n() が返す t() 関数（Composition API）を提供します。どちらも翻訳キーと、任意の名前付き／リスト形式の補間パラメーターを受け取ります。

src/locales/en.json
// src/locales/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {name}!",
  "cart": {
    "itemCount": "no items | one item | {count} items"
  }
}

// src/locales/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {name}!",
  "cart": {
    "itemCount": "keine Artikel | ein Artikel | {count} Artikel"
  }
}
4

複数形の処理

vue-i18n は、パイプ区切りの形式と $tc() 関数（legacy）、または件数パラメーターを渡す t()（Composition API）で複数形に対応します。ロケールメッセージでは、パイプ区切りで複数形式を定義します：'no items | one item | {count} items'。

MyComponent.vue
<template>
  <div>
    <!-- Simple translation -->
    <h1>{{ $t('nav.home') }}</h1>

    <!-- With variables -->
    <p>{{ $t('greeting', { name: userName }) }}</p>

    <!-- In attributes -->
    <input :placeholder="$t('nav.settings')" />

    <!-- Composition API -->
    <p>{{ greeting }}</p>
  </div>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
const userName = 'Alice'
const greeting = t('greeting', { name: userName })
</script>
パイプ区切りの複数形構文が対応するのは、最大 3 形式（zero | one | other）の基数（cardinal）の複数形だけです。複雑な CLDR 複数形規則を持つ言語（アラビア語、ロシア語、ポーランド語）では、ICU MessageFormat 構文、または CLDR カテゴリを明示的に対応付ける @.plural 修飾子を使用します。
5

ロケールフォールバックチェーンの追加

vue-i18n 組み込みの fallbackLocale は、ロケールごとのチェーンではなく、フラットなフォールバックロケール一覧にしか対応しません。そのため、pt-BR でキーが欠落すると pt-PT ではなく英語へフォールバックします。vue-i18n-locale-chain は構成可能なディープマージチェーンを追加し、地域別ロケールのユーザーに利用可能な最も近い翻訳を表示します。

Plurals.vue
<template>
  <div>
    <!-- Pipe-separated plurals -->
    <p>{{ $t('cart.itemCount', count) }}</p>

    <!-- Named plurals (recommended for complex languages) -->
    <p>{{ $t('orders', { n: orderCount }) }}</p>
  </div>
</template>

<!-- In your locale file: -->
<!-- "orders": "{n} order | {n} orders" -->
vue-i18n-locale-chain は、読み込み時にメッセージをディープマージします。統合したメッセージセットは vue-i18n のリアクティブシステムがキャッシュするため、フォールバック検索によるランタイムのパフォーマンス低下はありません。
6

翻訳の自動化

vue-i18n の設定後は、AI でロケール JSON ファイルを翻訳できます。IDE から AI アシスタントに翻訳元ファイルの翻訳を依頼するか、CI/CD パイプラインへ翻訳を組み込んで、ローカリゼーションを完全に自動化します。

LanguageSwitcher.vue
<template>
  <select v-model="locale">
    <option v-for="lang in availableLocales" :key="lang" :value="lang">
      {{ lang }}
    </option>
  </select>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { locale, availableLocales } = useI18n()
</script>
src/i18n.ts (lazy loading)
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  fallbackLocale: 'en',
  messages: {},
})

export async function loadLocale(locale: string) {
  const messages = await import(`./locales/${locale}.json`)
  i18n.global.setLocaleMessage(locale, messages.default)
  i18n.global.locale.value = locale
}

export default i18n
7

ロケールフォールバックチェーンの設定

地域別ロケールのユーザーが英語へ直接切り替わらず、利用可能な最も近い翻訳を参照できるよう、ロケールごとのフォールバックチェーンを設定します。vue-i18n では、オブジェクト形式の fallbackLocale でロケールごとのチェーンを定義できます。

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'pt-BR',
  fallbackLocale: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
    'es-419': ['es', 'en'],
    default: ['en'],
  },
  messages: {
    en: { /* ... */ },
    pt: { /* ... */ },
    'pt-BR': { /* ... */ },
  },
})
fallbackLocale オブジェクトでは、ロケールごとに異なるチェーンを定義できます。pt-BR ユーザーは pt、en の順、zh-Hant-TW ユーザーは zh-Hant、zh、en の順にフォールバックします。

よくある落とし穴

Legacy モードと Composition API モードの混在

legacy: true（標準設定）で useI18n() を使用するとエラーが発生します。Composition API を使う場合は createI18n() で legacy: false を設定するか、Options API のテンプレートで $t() を使用してください。同じアプリケーションで両モードを混在させないでください。

翻訳文字列に v-html を使用する

ユーザー入力由来の補間値がある場合、HTML を含む翻訳を v-html で描画すると XSS の危険があります。HTML または Vue コンポーネントを埋め込む翻訳には &lt;i18n-t&gt; コンポーネントを使用してください。標準で安全であり、リアクティブなコンポーネント埋め込みに対応します。

地域別ロケールのユーザーに親ロケールではなく英語が表示される

vue-i18n の fallbackLocale はフラットな一覧であり、ロケールごとのチェーンではありません。pt-BR は pt-PT を確認せず、一覧内のロケール（通常は「en」）へフォールバックします。ディープマージによる適切な地域フォールバックを追加するには、vue-i18n-locale-chain を使用してください。

i18n Agent を今すぐ試す

翻訳ファイルをここにドロップ

JSON, YAML, PO, XML, CSV, Markdown, Properties

またはクリックしてファイルを選択

翻訳先言語

登録不要すぐに見積もり

Vue i18n のよくある質問