next-i18nextからIntlayerへの移行

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

移行戦略

next-i18nextは裏側でreact-i18nextとi18nextをラップしているため、Intlayerへ移行するための互いに補完する2つの戦略があります：

1. 互換性アダプター（既存のアプリに推奨） — @intlayer/next-i18next、@intlayer/react-i18next、および@intlayer/i18nextをインストールします。これらのパッケージはそれらと全く同じAPIを公開しますが、すべての翻訳作業をIntlayerに委譲します。useTranslation、appWithTranslation、serverSideTranslations、およびNext.jsのページルーティングに対する既存の呼び出しはそのまま保持されます — 変更するのは初期化のみです。

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

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

目次

クイック移行

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

1. 1

   依存関係のインストール

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

   npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   npx intlayer init

   pnpm add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   pnpm intlayer init

   yarn add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   yarn intlayer init

   bun add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   bun x intlayer init

   移行中はnext-i18next、react-i18next、およびi18nextを安全にインストールしたままにしておけます（エイリアスが設定されたら削除します）。

2. 2

   Intlayerの設定

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

   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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;

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

3. 3

   Next.js設定の更新

   既存のnext.config.ts（または.js）を@intlayer/next-i18next/pluginのcreateNextI18nPluginでラップします。このラッパーはwithIntlayerを合成しつつ、next-i18next / react-i18next / i18next → @intlayer/*のエイリアスを注入するため、既存のimport { useTranslation } from 'next-i18next'がビルド時に透過的にリダイレクトされます。ソースファイルの変更は不要です。

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // next-i18next.config.jsからのi18n設定のインポートは削除できます
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayerが裏側でNext.jsのi18nルーティングを処理するため、
     // ここでi18nオブジェクトを渡す必要はありません。
   };
   
   export default withIntlayer(nextConfig);

   next-i18next.config.jsは不要になります。 Intlayerはすべての辞書をビルド時にコンパイルし、ロケール検出、ルーティング、辞書の読み込みをシームレスに処理します。

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

これでクイック移行は完了です。Next.jsアプリは、useTranslation、serverSideTranslations、およびappWithTranslationへのすべての呼び出しを保持したまま、Intlayer上で動作するようになります。

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

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

// getStaticProps / getServerSideProps (i18next インスタンス)
const tAbout = i18n.getFixedT(null, "about");
tAbout("counter.label"); // ✓ 型付け済み

完全移行

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

1. 4

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

   オプション

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

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

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

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

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

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

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: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // デフォルト
       // model: "gpt-4o-mini",   // デフォルト
     },
   };
   
   export default config;

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

移行後に削除できるもの

互換性アダプターが導入されると、以下のnext-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
• Next.js (Pages Router)とIntlayer — Next.jsの完全なセットアップガイド：intlayerwithnextjspagerouter.md