react-i18next / i18nextからIntlayerへの移行

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

移行戦略

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

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

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

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

目次

クイック移行

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

1. 1

   依存関係のインストール

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

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   react-i18nextとi18nextはインストールしたままにしておいて構いません — 互換性アダプターはそれらをTypeScriptの型のオプションのdevDependencies / peerDependenciesとして使用します。package.jsonのpeer設定を変更する必要はありません。

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

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

3. 3

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

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

   Viteの場合：

   vite.config.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";
   import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
   
   export default defineConfig({
     plugins: [react(), reactI18nextVitePlugin()],
   });

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

   Next.jsの場合：

   next-i18next（Pages Router統合）を使用している場合は、@intlayer/next-i18nextおよびnext-intlayerをインストールします：

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   npm install @intlayer/next-i18next next-intlayer

   次に、互換性プラグインをnext.config.tsに追加します（next-i18next / react-i18next / i18nextのエイリアスを注入します）：

   next.config.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     /* オプション */
   };
   
   export default withIntlayer(nextConfig);

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

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

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

tsx

コンテンツをコピー

コードをコピー

コードをクリップボードにコピー

// 'about' は登録済みの辞書のキーです → t() は有効なパスのみを受け入れますconst { t } = useTranslation("about");t("counter.label"); // ✓ オートコンプリートt("does.not.exist"); // ✗ TypeScript エラー// サーバー側 (i18next インスタンス)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ 型付け済み

完全移行

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

1. 4

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

   オプション

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

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

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

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

   変更前	変更後
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   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'

   Next.js (next-i18next) の場合：

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

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

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

   変更前	変更後
   import { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'

2. 5

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

移行後に削除できるもの

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

さらに進める準備ができたら、Intlayerはコードベース内のどこにある.content.tsおよび.content.jsonファイルでも自動的に検出します（デフォルトでは./src内）。my-component.content.tsファイルをMyComponent.tsxのすぐ隣に配置するだけで、追加の設定なしでビルド時に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
• ReactとIntlayer — Reactの完全なセットアップガイド：intlayerwithvite+react.md
• Next.jsとIntlayer — Next.jsの完全なセットアップガイド：intlayerwithnextjs_16.md