Creation:2026-06-05Last update:2026-06-05

    i18nextからIntlayerへの移行

    なぜi18nextからIntlayerに移行するのか？

    巨大なJSONファイルをページに読み込む代わりに、必要なコンテンツのみをロードします。Intlayerは、バンドルとページのサイズを最大50%削減するのに役立ちます。

    アプリケーションのコンテンツをスコープ化することで、大規模なアプリケーションのメンテナンスが容易になります。機能フォルダ全体を複製または削除しても、すべてのコンテンツコードベースを確認するという精神的負担がありません。さらに、Intlayerはコンテンツの正確性を確保するために完全に型付けされています。

    また、Intlayerはi18nエコシステムの中で最も活発に開発されているソリューションでもあります。問題は迅速に修正され、新しいフレームワークアダプタが定期的に登場し、コアAPIは実際の運用フィードバックに基づいて継続的に改良されています。

    コンテンツのコロケーション（同一場所配置）により、大規模言語モデル（LLM）に必要なコンテキストが減少します。Intlayerには、不足している翻訳をテストするためのCLI、LSP、MCP、およびエージェントスキルなどのツールスイートが備わっており、AIエージェントにとってよりスムーズな開発者体験（DX）を提供します。

    AIプロバイダーのコストで、お好みのLLMを使用してCI/CDパイプライン内で翻訳を自動化できます。Intlayerは、コンテンツ抽出を自動化するためのコンパイラや、バックグラウンドでの翻訳を支援するウェブプラットフォームも提供しています。

    コンポーネントに巨大なJSONファイルを接続すると、パフォーマンスやリアクティビティの問題が発生する可能性があります。Intlayerはビルド時にコンテンツのロードを最適化します。

    単なるi18nソリューションにとどまらず、IntlayerはセルフホストのビジュアルエディタとフルCMSを提供し、多言語コンテンツをリアルタイムで管理できるようにします。これにより、翻訳者やコピーライター、その他のチームメンバーとのシームレスなコラボレーションが可能になります。コンテンツはローカルおよび/またはリモートに保存できます。

    移行戦略

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

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

    2. 完全移行 — 徐々にi18nextのAPIをネイティブのIntlayerツールに置き換え、コンテンツを.content.tsファイル内にコロケーションします。

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

    目次

    クイック移行

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

    1. 依存関係のインストール

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

      bash
      npm install intlayer @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init
      i18nextはインストールしたままにして構いません — 互換性アダプターはこれをTypeScriptの型のためのdevDependency / peerDependencyとして使用します。

    2. Intlayerの設定

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

      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({
      // i18nextのプレースホルダー構文 {{name}} に一致させます
      format: "i18next",
      source: ({ locale }) => `./src/locales/${locale}.json`,
      location: "src/locales",
    }),
  ],
};

export default config;
      sourceはロケールをそのJSONファイルのパスにマッピングします。locationはIntlayerウォッチャーに変更を監視するフォルダを指示します。format: 'i18next'オプションは、{{name}}のようなプレースホルダーが正しく解析されることを保証します。

    3. バンドラエイリアスの更新（オプション）

      バンドラ（Vite、Webpack、esbuild）を使用している場合、モジュールエイリアスを注入して、import ... from 'i18next'が自動的に@intlayer/i18nextに解決されるようにすることができます。これにより、コードベース全体のインポートを手動で変更する必要がなくなります。

      Viteの場合：

      vite.config.ts
      import { defineConfig } from "vite";
import i18nextVitePlugin from "@intlayer/i18next/plugin";

export default defineConfig({
  plugins: [i18nextVitePlugin()],
});
      i18nextVitePlugin()はvite-intlayerのintlayer()プラグインをラップし、i18next → @intlayer/i18nextのエイリアスを自動的に追加します。通常のvite-intlayerのintlayer()プラグインを使用すると、辞書はコンパイルされますがエイリアスは追加されません — その場合、インポートを@intlayer/i18nextに手動で名前変更する必要があります（次のステップを参照）。

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

    完全移行

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

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

      オプション

      ソースファイル内で依存関係を明示したい場合、またはインポートをエイリアス化するためのバンドラプラグインを使用しない場合は、手動でインポート名を変更できます：

      変更前 変更後
      import i18next from 'i18next' import i18next from '@intlayer/i18next'
      import { createInstance } from 'i18next' import { createInstance } from '@intlayer/i18next'
      import { t } from 'i18next' import { t } from '@intlayer/i18next'

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

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

      オプション

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

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

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

      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: "i18next",
      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ドキュメントを確認してください。

    移行後に削除できるもの

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

    ファイル / パターン 不要になる理由
    i18next.init() 呼び出し Intlayerは自動的にすべてを初期化します。実行時のロードステップはありません。
    i18next.use(...) Intlayerはi18nextのプラグイン、バックエンド、言語検出機能を使用しません。
    JSON言語バンドル (locales/*.json) JSONバンドルは、syncJSONプラグインを使用している場合にのみ必要です。.content.tsファイルに移行したら、JSONフォルダを削除できます。

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

    TypeScriptの設定

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

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

    Git設定

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

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

    さらに詳しく

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