Creation:2026-01-10Last update:2026-05-31

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

    www.youtube.com

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

    目次

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

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

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

    Intlayerコンパイラとは？

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

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

    制限事項

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

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

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

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

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

      bash
      npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

      • intlayer

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

      • next-intlayer

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

    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. 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と完全に連携します。

    4. ページでのロケール検出

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

      src/app/layout.tsx
      import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, 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)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

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

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

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

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

      page.tsx の見た目の例：

      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>);}
      • IntlayerClientProvider は、クライアントサイドで子要素にロケールを提供するために使用されます。

      • 一方、 IntlayerServerProvider は、サーバーサイドで子要素にロケールを提供するために使用されます。

        Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

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

      オプション

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

      bash
      npx intlayer test         # 不足している翻訳があるかテスト
      bash
      npx intlayer fill         # 不足している翻訳を埋める
      詳細については、CLIドキュメントを参照してください。

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

      オプション

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

      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に保存することも可能です。

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

      オプション

      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 フックのドキュメント を参照してください。

    9. バンドルサイズの最適化

      オプション

      next-intlayer を使用する場合、デフォルトで各ページのバンドルに辞書が含まれます。バンドルサイズを最適化するために、Intlayerはマクロを使用して useIntlayer コールを賢く置き換えるオプションの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 を使用することはできなくなります。

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

      オプション

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

      このプロセスを容易にするために、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;

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

      bash
      npx intlayer extract

    Babel の構成

    Intlayerコンパイラは、コンテンツを抽出し最適化するためにBabelを必要とします。 babel.config.js（または babel.config.json）を更新してIntlayerプラグインを含めます：

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

    TypeScript 設定

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

    自動補完

    翻訳エラー

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

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

    Git 設定

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

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

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

    VS Code 拡張機能

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

    VS Code Marketplace からインストール

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

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

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

    さらに進む

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

    Next.jsとページルーター
    Tanstack Start