next-intlからIntlayerへの移行

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

移行戦略

既存のアプリケーションに推奨されるアプローチは互換性アダプターです：@intlayer/next-intlをインストールします。これはnext-intlと全く同じAPIを公開しますが、裏側ですべての翻訳作業をIntlayerに委譲します。

既存のuseTranslations、getTranslations、NextIntlClientProviderなどはそのまま保持されます — 変更するのはインポートパスのみです。呼び出しシグネチャ、プロパティの形、コンポーネント構造のリファクタリングは不要です。

将来的には、オプションとして個々のファイルをよりリッチなIntlayerの.content.ts形式に移行し、ビジュアルエディタ、CMS、コンポーネントレベルのコンテンツスコープを利用できるようにすることができます — ただし、このステップは完全にオプションであり、徐々に行うことができます。

目次

クイック移行

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

1. 1

   依存関係のインストール

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

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

   pnpm add intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
   pnpm intlayer init

   yarn add intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
   yarn intlayer init

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

   next-intlはインストールしたままにしておいてください — URLルーティング (createNavigation、createMiddleware、Link、redirect、usePathname、useRouter) のために引き続き必要です。互換性アダプターはルーティングレイヤーを置き換えません。

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({
         // 'icu'はnext-intlのICUプレースホルダー構文 {name}, {count, plural, ...} に一致させます
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;

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

   利用可能なすべての設定オプションについては、設定ドキュメントを参照してください。

3. 3

   IntlayerプラグインをNext.jsに追加する

   既存のNext.js設定を@intlayer/next-intl/pluginのcreateNextIntlPluginでラップします。このラッパーはwithIntlayerを合成しつつ、next-intl → @intlayer/next-intlのエイリアスを登録します：

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* 既存の設定オプション */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin()はwithIntlayerをラップし、WebpackまたはTurbopackを自動検出して、コンテンツ監視や辞書のコンパイルをフックアップし、最も重要なこととしてモジュールエイリアスを注入します。これにより、既存のimport … from 'next-intl'への呼び出しがビルド時に透過的に@intlayer/next-intlにリダイレクトされます。next-intl/routingのエントリは実際のパッケージを指し続けます。ソースファイルの変更は不要です。

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

   getRequestConfigやloadMessagesは不要になります。 next-intlでは、リクエストごとにgetRequestConfigを介してJSONメッセージバンドルを読み込むsrc/i18n.tsファイルを作成する必要がありました。Intlayerはすべての辞書をビルド時にコンパイルするため、実行時のロードステップはありません。このファイルは完全に削除できます（引き続きcreateNavigationを使用する場合は、ルーティングの部分だけを残してください）。

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

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

// クライアントコンポーネント — 'about' は登録済みの辞書のキーです
const t = useTranslations("about");
t("counter.label"); // ✓ オートコンプリート
t("does.not.exist"); // ✗ TypeScript エラー

// サーバーコンポーネント
const t = await getTranslations("about");
t("counter.label"); // ✓ 型付け済み

完全移行

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

1. 4

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

   オプション

   createNextIntlPlugin()ラッパーは既にバンドラレベルでのnext-intl → @intlayer/next-intlのエイリアス化を処理しています。ソースファイル内で依存関係を明示的にしたい場合（および代わりに通常のwithIntlayerプラグインを使用する場合）、手動でインポート名を変更できます：

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

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

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

   変更前	変更後
   import { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   実際のnext-intlからのルーティングのインポートは常に保持してください — 互換性アダプターはURLルーティングレイヤーを置き換えません：

   // ✅ これらは常に本物の 'next-intl' から維持する
   import { createNavigation } from "next-intl/routing";
   import { createMiddleware } from "next-intl/server";
   import { defineRouting } from "next-intl/routing";

   または、@intlayer/next-intl/routingからdefineRoutingを使用することで、intlayer.config.tsのロケール設定を自動的にマージすることができます。

2. 5

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

   オプション

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

   # 不足している翻訳をテスト（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

   .envファイルにOPENAI_API_KEY（またはお好みのプロバイダーのキー）を追加し、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 }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // デフォルト
       // model: "gpt-4o-mini",   // デフォルト
     },
   };
   
   export default config;

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

移行後に削除できるもの

@intlayer/next-intlが導入されると、以下のnext-intlのボイラープレートコードは削除できます：

さらに進める準備ができたら、Intlayerはコードベース内のどこにある.content.tsおよび.content.jsonファイルでも自動的に検出します（デフォルトでは./src内）。about.content.tsファイルをabout/page.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とIntlayer — Next.jsの完全なセットアップガイド：intlayerwithnextjs_16.md