vue-i18nからIntlayerへの移行

なぜvue-i18nからIntlayerに移行するのか？

移行戦略

vue-i18nからIntlayerに移行するための、互いに補完する2つの戦略があります：

1. 互換性アダプター（既存のアプリに推奨） — @intlayer/vue-i18n（Vueコンポーネント用）をインストールします。このパッケージはvue-i18nと全く同じAPIを公開しますが、すべての翻訳作業をIntlayerに委譲します。$t、useI18n()、および<i18n-t>への既存の呼び出しはそのまま保持されます — 変更するのはインポートパスと初期化のみです。

2. 完全移行 — 徐々にvue-i18nのAPIをネイティブのIntlayerフック（useIntlayer）に置き換え、コンポーネントと一緒に.content.tsファイル内にコンテンツをコロケーションします。

このガイドでは、まず戦略1（ドロップイン互換性アダプター）について解説し、その後オプションである完全移行について説明します。

目次

クイック移行

以下の手順は、コンポーネントのコードを変更せずに既存のvue-i18nアプリをIntlayer上で実行するために必要な最小限のステップです。

1. 1

   依存関係のインストール

   Intlayerのコアパッケージと互換性アダプターをインストールします：

   npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   npx intlayer init

   pnpm add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   pnpm intlayer init

   yarn add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   yarn intlayer init

   bun add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   bun x intlayer init

   vue-i18nはインストールしたままにしておいて構いません — 互換性アダプターはそれをTypeScriptの型のdevDependency / peerDependencyとして使用します。

2. 2

   Intlayerの設定

   intlayer initコマンドにより、初期のintlayer.config.tsファイルが作成されます。既存のロケールに合わせて設定を更新し、syncJSONプラグインがメッセージファイルを指すようにします：

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // 既存のすべてのロケールをここに追加します
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // vue-i18nのプレースホルダー構文 {name} に一致させます
         format: "icu",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   sourceはロケールをそのJSONファイルのパスにマッピングします。locationはIntlayerウォッチャーに監視するフォルダを指示します。format: 'icu'オプションは、vue-i18nのプレースホルダーが正しく解析されることを保証します。

3. 3

   バンドラへのIntlayerプラグインの追加

   既存のバンドラ設定を互換性プラグインでラップします。これはコアのIntlayerプラグインを合成し、コンテンツの監視をフックアップし、最も重要なこととしてモジュールエイリアスを注入するため、既存のimport … from 'vue-i18n'への呼び出しがビルド時に透過的に@intlayer/vue-i18nにリダイレクトされます。ソースファイルの変更は不要です。

   Viteの場合：

   import { defineConfig } from "vite";
   import vue from "@vitejs/plugin-vue";
   import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
   
   export default defineConfig({
     plugins: [vue(), vueI18nVitePlugin()],
   });

   vueI18nVitePlugin()はvite-intlayerのintlayer()プラグインをラップし、vue-i18nのエイリアスを追加します。通常のvite-intlayerのintlayer()プラグインを使用すると、辞書はコンパイルされますがエイリアスは追加されません — その場合、インポートを手動で@intlayer/vue-i18nに変更する必要があります（ステップ4を参照）。

   Nuxtの場合：

   @nuxtjs/i18n（Nuxt統合）を使用している場合は、nuxt-intlayerをインストールし、nuxt.config.tsに追加します：

   npm install nuxt-intlayer

   export default defineNuxtConfig({
     modules: ["nuxt-intlayer"],
     // @nuxtjs/i18nモジュールは安全に削除できます
   });

   createI18n()や手動のプロバイダーのブートストラップは不要になります。 Intlayerはすべての辞書をビルド時にコンパイルするため、実行時のロードステップはありません。エイリアスされたプロバイダーが初期化を処理します。

これでクイック移行は完了です。アプリはすべてのインポートとvue-i18nのAPIを保持したまま、Intlayer上で動作するようになります。

型付けされた翻訳キー — 自動的に。 Intlayerが辞書をコンパイルすると、namespaceオプションを渡した場合にuseI18nは実際のコンテンツに対して型付けされます。キーはIDEでオートコンプリートされ、無効なパスはビルド時にTypeScriptエラーを引き起こします — 追加の設定は必要ありません。

// 'about' は登録済みの辞書のキーです
const { t } = useI18n({ namespace: "about" });
t("counter.label"); // ✓ オートコンプリート
t("does.not.exist"); // ✗ TypeScript エラー

完全移行

以下のステップはオプションであり、段階的に行うことができます。これにより、ビジュアルエディタ、CMS、型付けされたコンテンツファイル、AIを利用した翻訳自動化など、Intlayerの全機能が解放されます。

1. 4

   インポートの明示的な変更（オプション）

   オプション

   Intlayerプラグインは既にバンドラレベルでのエイリアス化を処理しています。ソースファイル内で依存関係を明示的にしたい場合は、手動でインポート名を変更できます：

   テーブルのすべての内容を表示

   テーブルのすべての内容を表示

   テーブルをモーダルで開き、すべてのデータを明確に表示

   変更前	変更後
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'
   import { createI18n } from 'vue-i18n'	import { createI18n } from '@intlayer/vue-i18n'

   これらはドロップインの置き換えであり、呼び出しシグネチャ、引数、または戻り値の型を変更する必要はありません。

2. 5

   AIを利用した翻訳自動化の有効化

   オプション

   Intlayerが設定されたら、CLIを使用して不足している翻訳を自動入力することができます：

   # 不足している翻訳をテスト（CIに追加）
   npx intlayer test
   
   # 不足している翻訳をAIで埋める
   npx intlayer fill

   pnpm intlayer test
   pnpm intlayer fill

   yarn intlayer test
   yarn intlayer fill

   bun x intlayer test
   bun x intlayer fill

   AI設定をintlayer.config.tsに追加します：

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "icu",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // デフォルト
       // model: "gpt-4o-mini",   // デフォルト
     },
   };
   
   export default config;

   利用可能なすべてのオプションについては、Intlayer CLIドキュメントを確認してください。

移行後に削除できるもの

互換性アダプターが導入されると、以下のvue-i18nのボイラープレートコードは削除できます：

さらに進める準備ができたら、Intlayerはコードベース内のどこにある.content.tsおよび.content.jsonファイルでも自動的に検出します（デフォルトでは./src内）。my-component.content.tsファイルをMyComponent.vueのすぐ隣に配置するだけで、追加の設定なしでビルド時にIntlayerがそれを取得します — インポート、登録、中央のインデックスファイルは不要です。これにより、ページやコンポーネントとの翻訳のコロケーションが完全にシームレスになります。

TypeScriptの設定

Intlayerはモジュール拡張を使用して、翻訳キーに対する完全なTypeScriptのIntelliSense（自動補完）を提供します。tsconfig.jsonに自動生成された型が含まれていることを確認してください：

{
  // ... 既存のTypeScript設定
  "include": [
    // ... 既存のTypeScript設定
    ".intlayer/**/*.ts", // 自動生成された型を含める
  ],
}

Git設定

Intlayerによって生成されたディレクトリを.gitignoreに追加します：

# Intlayer生成ファイルを無視
.intlayer

さらに詳しく

• ビジュアルエディタ — ブラウザ上で翻訳を視覚的に管理：Intlayer Visual Editor
• CMS — コンテンツを外部化してリモートで管理：Intlayer CMS
• VS Code拡張機能 — 翻訳の自動補完とエラー検出をリアルタイムで取得：Intlayer VS Code Extension
• CLIリファレンス — コマンドの完全なリスト：Intlayer CLI
• VueとIntlayer — Vueの完全なセットアップガイド：intlayerwithvite+vue.md
• NuxtとIntlayer — Nuxtの完全なセットアップガイド：intlayerwithnuxt.md