このページとあなたの好きなAIアシスタントを使ってドキュメントを要約します
バージョン履歴
- "Solid の useIntlayer API の使用法を直接プロパティアクセスに更新"v8.9.02026/5/4
- "Update compiler options, add FilePathPattern support"v8.2.02026/3/9
- "初期リリース"v8.1.62026/2/23
このページのコンテンツはAIを使用して翻訳されました。
英語の元のコンテンツの最新バージョンを見るこのドキュメントを改善するアイデアがある場合は、GitHubでプルリクエストを送信することで自由に貢献してください。
ドキュメントへのGitHubリンクドキュメントのMarkdownをクリップボードにコピー
既存の Next.js アプリケーションを多言語化 (i18n) する方法 (i18n ガイド 2026)
GitHubでアプリケーションテンプレートをご覧ください。
目次
なぜ既存のアプリケーションの国際化は難しいのか？
単一言語用に構築されたアプリに複数の言語を追加しようとしたことがあるなら、その苦労はご存知でしょう。「難しい」というだけでなく、退屈で面倒な作業です。すべてのファイルを調べ、すべてのテキスト文字列を見つけ出し、それらを別々の辞書ファイルに移動しなければなりません。
その後、レイアウトやロジックを壊すことなく、すべてのテキストをコードフックで置き換えるというリスクの高い作業が待っています。これは新機能の開発を数週間にわたって停止させ、終わりのないリファクタリングのように感じられるような作業です。
Intlayerコンパイラとは？
Intlayerコンパイラは、そのような手作業を回避するために作られました。手動で文字列を抽出する代わりに、コンパイラがそれを自動で行います。コードをスキャンし、テキストを見つけ、バックグラウンドでAIを使用して辞書を生成します。 その後、ビルドステップ中にソースコードを変更し、必要なi18nフックを注入します。基本的に、あなたは単一言語であるかのようにアプリケーションを書き続けるだけで、コンパイラが多言語への変換処理をネイティブに処理します。
コンパイラのドキュメント: /ja/doc/compiler
制限事項
コンパイラはコンパイル時にコードの解析と変換（フックの注入や辞書の生成）を行うため、アプリケーションのビルド時間が遅くなる可能性があります。
アクティブな開発中（devモード）のこの影響を制限するために、コンパイラを 'build-only' モードに設定するか、不要な場合は無効にすることができます。
Next.jsアプリケーションでのIntlayer設定ステップバイステップガイド
ステップ1: 依存関係のインストール
好みのパッケージマネージャーを使用して必要なパッケージをインストールします：
コードをクリップボードにコピー
npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer initintlayer
next-intlayer
IntlayerをNext.jsと統合するパッケージ。Next.jsの国際化のためのコンテキストプロバイダーとフックを提供します。さらに、IntlayerをWebpackまたはTurbopackと統合するためのNext.jsプラグイン、ユーザーの優先ロケールを検出、Cookie管理、URLリダイレクトを処理するためのミドルウェアが含まれています。
ステップ2: プロジェクトの構成
アプリケーションの言語を定義するための設定ファイルを作成します：
コードをクリップボードにコピー
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を使用するように構成します：
コードをクリップボードにコピー
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と完全に連携します。Babel の構成
Intlayerコンパイラは、コンテンツを抽出し最適化するためにBabelを必要とします。 babel.config.js（または babel.config.json）を更新してIntlayerプラグインを含めます：
コードをクリップボードにコピー
const { intlayerExtractBabelPlugin, intlayerOptimizeBabelPlugin, getExtractPluginOptions, getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [ [intlayerExtractBabelPlugin, getExtractPluginOptions()], [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()], ],};ステップ4: ページでのロケール検出
RootLayout の内容をクリアし、以下の例に置き換えます：
コードをクリップボードにコピー
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 の見た目の例：
コードをクリップボードにコピー
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.
(オプション) ステップ 7: 不足している翻訳を埋める
Intlayerは、不足している翻訳を埋めるためのCLIツールを提供しています。 intlayer コマンドを使用して、コード内の不足している翻訳をテストして埋めることができます。
コードをクリップボードにコピー
npx intlayer test # 不足している翻訳があるかテストコードをクリップボードにコピー
npx intlayer fill # 不足している翻訳を埋める詳細については、CLIドキュメントを参照してください。
(オプション) ステップ 8: ローカライズされたルーティングプロキシミドルウェア
ユーザーを優先ロケールに自動的にリダイレクトしたい場合は、プロキシミドルウェアを設定します：
コードをクリップボードにコピー
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に保存することも可能です。(オプション) ステップ 9: コンテンツの言語を変更する
Next.js内でコンテンツの言語を変更する最も推奨される方法は、 Link コンポーネントを使用してユーザーを適切な言語ルートに誘導することです。これにより、Next.jsのプリフェッチ機能を活用し、ページ全体がハードリフレッシュされるのを防ぐことができます。
コードをクリップボードにコピー
"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: バンドルサイズの最適化
next-intlayer を使用する場合、デフォルトで各ページのバンドルに辞書が含まれます。バンドルサイズを最適化するために、Intlayerはマクロを使用して useIntlayer コールを賢く置き換えるオプションのSWCプラグインを提供しています。これにより、辞書は実際に使用されるページのバンドルにのみ含まれるようになります。
この最適化を有効にするには、 @intlayer/swc パッケージをインストールします。インストール後、 next-intlayer は自動的にプラグインを検出して使用します：
コードをクリップボードにコピー
npm install @intlayer/swc --save-dev注: この最適化は Next.js 13 以降でのみ利用可能です。
注: Next.js の SWC プラグインはまだ試験段階であるため、このパッケージはデフォルトではインストールされていません。これは将来的に変更される可能性があります。
注: （辞書設定で）importMode: 'dynamic'またはimportMode: 'fetch'を設定した場合、Suspense に依存するため、useIntlayerコールをSuspense境界で囲む必要があります。そのため、ページ / レイアウトコンポーネントのトップレベルで直接useIntlayerを使用することはできなくなります。
TypeScript 設定
Intlayerは、TypeScriptの利点を活用し、コードベースをより堅牢にするためにモジュール拡張（module augmentation）を使用しています。
TypeScriptの設定に自動生成された型が含まれていることを確認してください。
コードをクリップボードにコピー
{ // ... 既存の TypeScript 設定 "include": [ // ... 既存の TypeScript 設定 ".intlayer/**/*.ts", // 自動生成された型を含める ],}Git 設定
Intlayerによって生成されたファイルを無視することを推奨します。これにより、Gitリポジトリにコミットされるのを防ぎます。
これを行うには、 .gitignore ファイルに以下の指示を追加します：
コードをクリップボードにコピー
# Intlayerによって生成されたファイルを無視.intlayerVS Code 拡張機能
Intlayerでの開発体験を向上させるために、公式の Intlayer VS Code 拡張機能 をインストールできます。
この拡張機能は以下を提供します：
- 翻訳キーの 自動補完。
- 不足している翻訳の リアルタイムエラー検出。
- 翻訳されたコンテンツの インラインプレビュー。
- 翻訳を簡単に作成・更新できる クイックアクション。
拡張機能の使用方法の詳細については、 Intlayer VS Code 拡張機能のドキュメント を参照してください。
(オプション) ステップ 1 : コンポーネントのコンテンツを抽出する
既存のコードベースがある場合、数千のファイルを変換するのは時間がかかることがあります。
このプロセスを容易にするために、Intlayerは、コンポーネントを変換しコンテンツを抽出するための コンパイラ / エクストラクタ を提案しています。
セットアップするには、intlayer.config.ts ファイルに compiler セクションを追加します。
コードをクリップボードにコピー
import { type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
// ... 他の構成
compiler: {
/**
* コンパイラを有効にするかどうかを指定します。
*/
enabled: true,
/**
* 出力ファイルのパスを定義します。
*/
output: ({ fileName, extension }) => `./${fileName}${extension}`,
/**
* 変換後にコンポーネントを保存するかどうかを指定します。これにより、コンパイラを一度だけ実行してアプリを変換し、その後削除することができます。
*/
saveComponents: false,
/**
* 辞書キーの接頭辞
*/
dictionaryKeyPrefix: "",
},
};
export default config;コンポーネントを変換してコンテンツを抽出するためにエクストラクタを実行します
コードをクリップボードにコピー
npx intlayer extractさらに進む
さらに進めるには、 ビジュアルエディター を実装したり、 CMS を使用してコンテンツを外部管理化したりできます。