vue-i18n-skilld

vue-i18n 11.4.12（Vue 3）

Vue.js 用の国際化プラグインです。

• ピア依存関係：vue ^3.0.0（package.json:44）。Vue 2 はサポートされていません。Vue 2 では vue-i18n v8 を使用してください。
• Node エンジン：>= 22（package.json:47）。
• Nuxt 3 では、これを直接インストールするのではなく、@nuxtjs/i18n を使用してください（https://vue-i18n.intlify.dev/guide/integrations/nuxt3.html）。

基本ルール

1. Composition API モードをデフォルトにしてください。 createI18n に legacy: false を渡し、useI18n() を使用してください。Legacy API モード（legacy: true、デフォルト）は v11 で非推奨になり、v12 で削除されます（dist/vue-i18n.d.ts:1728）。
2. 新しいコードでは v-t ディレクティブを使用しないでください。 v11 で非推奨になり、v12 で削除されます（dist/vue-i18n.d.ts:2138）。t()、$t、または <i18n-t> コンポーネントを使用してください。
3. tc と $tc は存在しなくなりました。 v11 で削除されました。複数形の処理は t／$t が複数形オプションを通じて行います（確認済み：dist/vue-i18n.d.ts に tc のエクスポートはありません）。
4. 補間には {name} 構文を使用します。 v8 の剰余演算子 % 構文は v10 で削除されました（https://vue-i18n.intlify.dev/guide/migration/breaking10.html#drop-modulo-syntax）。
5. v10 以降、メッセージはデフォルトで実行時にコンパイル（JIT）されます。 CSP を厳格に適用する環境や最高のパフォーマンスが必要な場合は、@intlify/unplugin-vue-i18n で事前コンパイルしてください（https://vue-i18n.intlify.dev/guide/advanced/optimization.html）。
6. v-html でレンダリングするメッセージに、ユーザー入力をエスケープせずに補間しないでください。 escapeParameter: true を指定してください。コンテンツを翻訳し、HTML を連結しないでください。

セットアップ

// i18n.js
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false, // Composition API mode
  locale: 'ja',
  fallbackLocale: 'en',
  messages: {
    en: { message: { hello: 'hello world' } },
    ja: { message: { hello: 'こんにちは、世界' } }
  }
})

export default i18n

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n'

createApp(App).use(i18n).mount('#app')

app.use(i18n) は $t／$d／$n／$rt のグローバルプロパティをインストールし（globalInjection: true の場合。デフォルト）、useI18n を有効にし、i18n-t、i18n-d、i18n-n をグローバル登録します（globalInstall: true の場合。デフォルト。dist/vue-i18n.d.ts:1810-1822）。

コンポーネントで翻訳する

<script setup>
import { useI18n } from 'vue-i18n'
const { t, locale } = useI18n()
</script>

<template>
  <h1>{{ t('message.hello') }}</h1>
  <p>{{ t('greeting', { name: 'Kyoko' }) }}</p>
  <p>{{ $t('message.hello') }}</p>
</template>

useI18n() は setup 内でのみ呼び出してください。それ以外で呼び出すと、"Must be called at the top of a setup function" というエラーがスローされます。

よくあるタスク

複数形にする。 メッセージ：'no apples | one apple | {count} apples'（パイプで区切られた形式。ロケールの複数形ルールに基づいて選択されます）。

t('apple', count, { count }) // or t('apple', { count }, choice)

カスタムルール：Composer オプション（Composition）では pluralRules、Legacy では pluralizationRules を使用します。

日付と数値をフォーマットする。

const { d, n } = useI18n()
d(new Date(), 'long') // named format from datetimeFormats option, else Intl fallback
n(1234567, 'currency') // named format from numberFormats option

コンポーネントを補間する。 <i18n-t keypath="..." tag="p"> を使用し、各プレースホルダーに対応する子要素をスロットとして指定してください。コンポーネントを参照してください。

ロケールを切り替える。 Composer から locale.value = 'en' を設定します。また、ドキュメントの lang 属性と、SSR では Accept-Language の処理も更新してください（https://vue-i18n.intlify.dev/guide/advanced/lazy.html）。

ロケールを遅延読み込みする。 動的な import() と setLocaleMessage／mergeLocaleMessage を使用してください。最適化を参照してください。

型安全なキー

グローバルの DefineLocaleMessage、DefineDateTimeFormat、DefineNumberFormat インターフェースを拡張すると、ジェネリクスを指定せずに useI18n でキーの補完と型推論が利用できます。TypeScriptを参照してください。

注意点

• useI18n({ messages: ... }) はローカルスコープを作成します。useScope: 'global' を指定しない場合、ローカルメッセージはグローバルメッセージとマージされません（https://vue-i18n.intlify.dev/guide/essentials/scope.html）。
• Composition モードでテンプレート内の $t を使うには、globalInjection: true が必要です（dist/vue-i18n.d.ts:1735-1746）。
• キー自体にフォールバックするロケールメッセージが見つからない場合、Vue は警告を表示します。ノイズを調整するには missing／missingWarn／fallbackWarn を設定してください。
• リンクメッセージ（@:key）、リテラルの { }、およびメッセージ内の @ | はエスケープが必要です。メッセージ構文を参照してください。
• バンドラープロジェクトでは、vue-i18n/dist/* のような深いパスからインポートしないでください。適切なビルドが解決されるよう、パッケージのルートを使用してください（package.json:63-83）。

移行状況

変更	バージョン	対応
レガシー API モードの非推奨化	v11	v12 より前に legacy: false に変更します（dist/vue-i18n.d.ts:1728）
v-t ディレクティブの非推奨化	v11	t()/$t/<i18n-t> に置き換えます（dist/vue-i18n.d.ts:2138）
tc/$tc の削除	v11	複数形オプションに t/$t を使用します
JIT メッセージコンパイルのデフォルト化	v10	厳格な CSP では事前コンパイルします
% 名前付き補間の削除	v10	{name} を使用します
$t の位置引数オーバーロードの変更	v10	オプションオブジェクトを使って複数形を渡します

詳細：移行。

参考資料

• コンポジション API：createI18n、useI18n、Composer のメンバー、スコープ、ロケールの切り替え
• メッセージ構文：補間、複数形、リンクされたメッセージ、HTML の安全性
• コンポーネント：i18n-t、i18n-n、i18n-d
• フォーマット：日時と数値のフォーマット、カスタムフォーマット定義
• TypeScript：スキーマの型付け、生成されたロケール型
• 最適化：ツリーシェイキングフラグ、事前コンパイル、遅延読み込み、dist ファイル
• 移行：v9、v10、v11 の破壊的変更と v12 での削除
• レガシー API：v11 でも引き続き利用できるレガシー API モードの機能

公式ドキュメント：https://vue-i18n.intlify.dev/ API リファレンス：https://vue-i18n.intlify.dev/api/general.html 変更履歴（引用のみ、転載なし）：https://github.com/intlify/vue-i18n/blob/master/CHANGELOG.md