既存の Next.js アプリケーションを多言語化 (i18n) する方法 (i18n ガイド 2026)

動画コード

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

GitHubでアプリケーションテンプレートをご覧ください。

目次

なぜ既存のアプリケーションの国際化は難しいのか？

単一言語用に構築されたアプリに複数の言語を追加しようとしたことがあるなら、その苦労はご存知でしょう。「難しい」というだけでなく、退屈で面倒な作業です。すべてのファイルを調べ、すべてのテキスト文字列を見つけ出し、それらを別々の辞書ファイルに移動しなければなりません。

その後、レイアウトやロジックを壊すことなく、すべてのテキストをコードフックで置き換えるというリスクの高い作業が待っています。これは新機能の開発を数週間にわたって停止させ、終わりのないリファクタリングのように感じられるような作業です。

Intlayerコンパイラとは？

Intlayerコンパイラは、そのような手作業を回避するために作られました。手動で文字列を抽出する代わりに、コンパイラがそれを自動で行います。コードをスキャンし、テキストを見つけ、バックグラウンドでAIを使用して辞書を生成します。 その後、ビルドステップ中にソースコードを変更し、必要なi18nフックを注入します。基本的に、あなたは単一言語であるかのようにアプリケーションを書き続けるだけで、コンパイラが多言語への変換処理をネイティブに処理します。

コンパイラのドキュメント: /ja/doc/compiler

制限事項

コンパイラはコンパイル時にコードの解析と変換（フックの注入や辞書の生成）を行うため、アプリケーションのビルド時間が遅くなる可能性があります。

アクティブな開発中（devモード）のこの影響を制限するために、コンパイラを 'build-only' モードに設定するか、不要な場合は無効にすることができます。

Next.jsアプリケーションでのIntlayer設定ステップバイステップガイド

1. 1

   依存関係のインストール

   好みのパッケージマネージャーを使用して必要なパッケージをインストールします：

   bash

   コンテンツをコピー

   コードをコピー

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

   npx intlayer init --interactive
   

   --interactive フラグはオプションです。AI エージェントの場合は intlayer-cli init を使用してください。

   このコマンドは環境を検出し、必要なパッケージをインストールします。例えば：

   bash

   コンテンツをコピー

   コードをコピー

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

   npm install intlayer next-intlayer
   npm install @intlayer/babel --save-dev
   

   • intlayer

     構成管理、翻訳、コンテンツ宣言、トランスパイル、CLIコマンドのための国際化ツールを提供するコアパッケージ。

   • next-intlayer

     IntlayerをNext.jsと統合するパッケージ。Next.jsの国際化のためのコンテキストプロバイダーとフックを提供します。さらに、IntlayerをWebpackまたはTurbopackと統合するためのNext.jsプラグイン、ユーザーの優先ロケールを検出、Cookie管理、URLリダイレクトを処理するためのミドルウェアが含まれています。

2. 2

   プロジェクトの構成

   アプリケーションの言語を定義するための設定ファイルを作成します：

   intlayer.config.ts

   コンテンツをコピー

   コードをコピー

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

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.JAPANESE],
       defaultLocale: Locales.JAPANESE,
     },
     routing: {
       mode: "search-params",
     },
     compiler: {
       /**
        * コンパイラを有効にするかどうかを示します。
        */
       enabled: true,
   
       /**
        * 最適化された辞書の出力ディレクトリ。
        */
       output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
   
       /**
        * キーなしで、生成されたファイルにコンテンツのみを挿入します。
        */
       noMetadata: false,
   
       /**
        * 辞書キーのプレフィックス
        */
       dictionaryKeyPrefix: "", // Remove base prefix
   
       /**
        * 変換後にコンポーネントを保存するかどうかを示します。
        * これにより、コンパイラを1回だけ実行してアプリを変換し、その後削除することができます。
        */
       saveComponents: false,
     },
     ai: {
       provider: "openai",
       model: "gpt-5-mini",
       apiKey: process.env.OPEN_AI_API_KEY,
       applicationContext: "これはシンプルな地図アプリケーションの例です",
     },
   };
   
   export default config;
   

   注: 環境変数に OPEN_AI_API_KEY が設定されていることを確認してください。

   この設定ファイルを使用して、ローカライズされたURL、プロキシリダイレクト、Cookieマッピング、コンテンツ宣言の場所と拡張子の設定、コンソールでのIntlayerログの無効化などを行えます。使用可能なパラメータの完全なリストについては、設定ドキュメントを参照してください。

3. 3

   Next.jsの設定にIntlayerを統合する

   Next.jsのセットアップをIntlayerを使用するように構成します：

   next.config.ts

   コンテンツをコピー

   コードをコピー

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

   import type { NextConfig } from "next";
   import { withIntlayer } from "next-intlayer/server";
   
   const nextConfig: NextConfig = {
     /* ここにオプションで追加のNext.js設定を記述 */
   };
   
   export default withIntlayer(nextConfig);
   

   withIntlayer() Next.jsプラグインは、IntlayerとNext.jsを統合するために使用されます。これにより辞書ファイルがビルドされ、devモードで監視されます。WebpackまたはTurbopack環境内でIntlayer環境変数を定義します。さらに、パフォーマンスを最適化するためのエイリアスを提供し、Server Componentsと完全に連携します。

</Step>

4. 4

   ページでのロケール検出

   Intlayer コンパイラーは、コンテンツを抽出および最適化するために Babel が必要です。Intlayer プラグインを含めるように babel.config.js (または babel.config.json) を更新してください:

   babel.config.js

   コンテンツをコピー

   コードをコピー

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

   const {
     intlayerExtractBabelPlugin,
     intlayerOptimizeBabelPlugin,
     getExtractPluginOptions,
     getOptimizePluginOptions,
   } = require("@intlayer/babel");
   
   module.exports = {
     presets: ["next/babel"],
     plugins: [
       [intlayerExtractBabelPlugin, getExtractPluginOptions()],
       [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
     ],
   };
   

5. 5

   ページでロケールを検出する

   RootLayout の内容をクリアし、以下の例に置き換えます：

   src/app/layout.tsx

   コンテンツをコピー

   コードをコピー

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

   import type { Metadata } from "next";
   import type { ReactNode } from "react";
   import "./globals.css";
   import { IntlayerProvider, LocalPromiseParams } from "next-intlayer";
   import { getHTMLTextDir, getIntlayer } from "intlayer";
   import { getLocale } from "next-intlayer/server";
   export { generateStaticParams } from "next-intlayer";
   
   export const generateMetadata = async (): Promise<Metadata> => {
     const locale = await getLocale();
     const { title, description, keywords } = getIntlayer("metadata", locale);
   
     return {
       title,
       description,
       keywords,
     };
   };
   
   const RootLayout = async ({
     children,
   }: Readonly<{
     children: ReactNode;
   }>) => {
     const locale = await getLocale();
   
     return (
       <html lang={locale} dir={getHTMLTextDir(locale)}>
         <body>
           <IntlayerProvider defaultLocale={locale}>{children}</IntlayerProvider>
         </body>
       </html>
     );
   };
   
   export default RootLayout;
   

6. 5

   コンテンツを宣言する（自動）

   コンパイラを有効にすると、コンテンツ辞書（.content.tsファイルなど）を手動で宣言する必要がなくなります。

   代わりに、コード内にハードコードされた文字列としてコンテンツを書くだけです。Intlayerはソースコードをスキャンし、構成されたAIプロバイダーを使用して翻訳を生成し、ビルドのコンパイルステップ中にそれらの文字列をローカライズされたコンテンツに静かに置き換えます。これらすべてが完全に自動化されています。

   デフォルトのロケールでハードコードされた文字列を使用してコンポーネントを記述し、残りはIntlayerコンパイラに任せます。

   page.tsx の見た目の例：

   CodeOutput

   src/app/page.tsx

   コンテンツをコピー

   コードをコピー

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

   import type { FC } from "react";
   import { IntlayerServerProvider } from "next-intlayer/server";
   import { getLocale } from "next-intlayer/server";
   
   const PageContent: FC = () => {
     return (
       <>
         <p>編集を始めてみましょう！</p>
         <code>src/app/page.tsx</code>
       </>
     );
   };
   
   export default async function Page() {
     const locale = await getLocale();
   
     return (
       <IntlayerServerProvider locale={locale}>
         <PageContent />
       </IntlayerServerProvider>
     );
   }
   
7. 7

   不足している翻訳を埋める

   オプション

   Intlayerは、不足している翻訳を埋めるためのCLIツールを提供しています。 intlayer コマンドを使用して、コード内の不足している翻訳をテストして埋めることができます。

   bash

   コンテンツをコピー

   コードをコピー

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

   npx intlayer test         # 不足している翻訳があるかテスト
   

   bash

   コンテンツをコピー

   コードをコピー

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

   npx intlayer fill         # 不足している翻訳を埋める
   

   詳細については、CLIドキュメントを参照してください。

8. 8

   ローカライズされたルーティングプロキシミドルウェア

   オプション

   ユーザーを優先ロケールに自動的にリダイレクトしたい場合は、プロキシミドルウェアを設定します：

   src/proxy.ts

   コンテンツをコピー

   コードをコピー

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

   export { intlayerProxy as proxy } from "next-intlayer/proxy";
   
   export const config = {
     matcher:
       "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
   };
   

   intlayerProxy は、ユーザーの優先ロケールを検出し、設定ファイルのセッティングに従って適切なURLにリダイレクトするために使用されます。また、ユーザーの優先ロケールをCookieに保存することも可能です。

   Intlayer v9 以降、このミドルウェアは routing.enableProxy オプション（デフォルトでは true）を尊重します。このファイルを削除せずにパススルーに変更するには、設定で routing.enableProxy: false を設定してください。v9 リリースノートを参照してください。

9. 9

   コンテンツの言語を変更する

   オプション

   Next.js内でコンテンツの言語を変更する最も推奨される方法は、 Link コンポーネントを使用してユーザーを適切な言語ルートに誘導することです。これにより、Next.jsのプリフェッチ機能を活用し、ページ全体がハードリフレッシュされるのを防ぐことができます。

   src/components/localeSwitcher/LocaleSwitcher.tsx

   コンテンツをコピー

   コードをコピー

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

   "use client";
   
   import type { FC } from "react";
   import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
   import { useLocale } from "next-intlayer";
   
   export const LocaleSwitcher: FC = () => {
     const { locale, availableLocales, setLocale } = useLocale();
   
     return (
       <div>
         <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <button
               key={localeItem}
               aria-current={locale === localeItem ? "page" : undefined}
               onClick={() => setLocale(localeItem)}
             >
               <span>
                 {/* ロケール表記 - 例: JA */}
                 {localeItem}
               </span>
               <span>
                 {/* 現在のロケールに基づいた言語名 - 例: 日本語 */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* 指定されたロケール自体の言語での表記 - 例: Francés (現在のロケールが Locales.SPANISH の場合) */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* 英語での表記 - 例: Japanese */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </button>
           ))}
         </div>
       </div>
     );
   };
   

   別の方法として、 useLocale フックの setLocale 関数を使用することもできますが、こちらはページプリフェッチを許可しません。詳細については、 useLocale フックのドキュメント を参照してください。

10. 10

    バンドルサイズの最適化

    オプション

    next-intlayer を使用する場合、デフォルトで各ページのバンドルに辞書が含まれます。バンドルサイズを最適化するために、Intlayerはマクロを使用して useIntlayer コールを賢く置き換えるオプションのSWCプラグインを提供しています。これにより、辞書は実際に使用されるページのバンドルにのみ含まれるようになります。

    @intlayer/babel プラグインはすでにバンドリング最適化を統合しています（babel.config.js を参照）。しかし、@intlayer/swc プラグインはより高性能です。@intlayer/babel プラグインを削除すれば、@intlayer/swc プラグインを使用できます。

    この最適化を有効にするには、 @intlayer/swc パッケージをインストールします。インストール後、 next-intlayer は自動的にプラグインを検出して使用します：

    bash

    コンテンツをコピー

    コードをコピー

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

    npm install @intlayer/swc --save-dev
    

    注: この最適化は Next.js 13 以降でのみ利用可能です。

    注: Next.js の SWC プラグインはまだ試験段階であるため、このパッケージはデフォルトではインストールされていません。これは将来的に変更される可能性があります。

    注: （辞書設定で） importMode: 'dynamic' または importMode: 'fetch' を設定した場合、Suspense に依存するため、 useIntlayer コールを Suspense 境界で囲む必要があります。そのため、ページ / レイアウトコンポーネントのトップレベルで直接 useIntlayer を使用することはできなくなります。

</Step>

11. 1

    コンポーネントのコンテンツを抽出する

    オプション

    既存のコードベースがある場合、数千のファイルを変換するのは時間がかかることがあります。

    このプロセスを容易にするために、Intlayerは、コンポーネントを変換しコンテンツを抽出するための コンパイラ / エクストラクタ を提案しています。

    セットアップするには、intlayer.config.ts ファイルに compiler セクションを追加します。

    intlayer.config.ts

    コンテンツをコピー

    コードをコピー

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

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... 他の構成
      compiler: {
        /**
         * コンパイラを有効にするかどうかを指定します。
         */
        enabled: true,
    
        /**
         * 出力ファイルのパスを定義します。
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * 変換後にコンポーネントを保存するかどうかを指定します。これにより、コンパイラを一度だけ実行してアプリを変換し、その後削除することができます。
         */
        saveComponents: false,
    
        /**
         * 辞書キーの接頭辞
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    抽出コマンドBabelコンパイラ

    コンポーネントを変換してコンテンツを抽出するためにエクストラクタを実行します

    bash

    コンテンツをコピー

    コードをコピー

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

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    bash

    コンテンツをコピー

    コードをコピー

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

    npm install @intlayer/babel --save-dev
    

    babel.config.js

    コンテンツをコピー

    コードをコピー

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

    const {
      intlayerExtractBabelPlugin,
      getExtractPluginOptions,
    } = require("@intlayer/babel");
    
    module.exports = {
      presets: ["next/babel"],
      plugins: [
        // コンポーネントから辞書へコンテンツを抽出する
        [intlayerExtractBabelPlugin, getExtractPluginOptions()],
      ],
    };
    

    bash

    コンテンツをコピー

    コードをコピー

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

    npm run build # または npm run dev
    

TypeScript 設定

Intlayerは、TypeScriptの利点を活用し、コードベースをより堅牢にするためにモジュール拡張（module augmentation）を使用しています。

TypeScriptの設定に自動生成された型が含まれていることを確認してください。

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

Git 設定

Intlayerによって生成されたファイルを無視することを推奨します。これにより、Gitリポジトリにコミットされるのを防ぎます。

これを行うには、 .gitignore ファイルに以下の指示を追加します：

# Intlayerによって生成されたファイルを無視
.intlayer

VS Code 拡張機能

Intlayerでの開発体験を向上させるために、公式の Intlayer VS Code 拡張機能 をインストールできます。

VS Code Marketplace からインストール

この拡張機能は以下を提供します：

• 翻訳キーの 自動補完。
• 不足している翻訳の リアルタイムエラー検出。
• 翻訳されたコンテンツの インラインプレビュー。
• 翻訳を簡単に作成・更新できる クイックアクション。

拡張機能の使用方法の詳細については、 Intlayer VS Code 拡張機能のドキュメント を参照してください。

さらに進む

さらに進めるには、 ビジュアルエディター を実装したり、 CMS を使用してコンテンツを外部管理化したりできます。