# General Translation Knowledge Base: Next.js App Router アプリに i18n を追加するには？
URL: https://generaltranslation.com/ja/kb/add-i18n-to-nextjs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: まず gt init を実行して、対応する App Router プロジェクトに General Translation を設定します。次にソースコンテンツをマークし、翻訳を生成して、言語の切り替えが機能することを確認します。gt-next はテキストを翻訳の文脈とともに JSX 内に保持し、生成、レビュー、継続的な更新は CLI、ダッシュボード エディター、Locadex が担います。このガイドでは、ローカルファイルを明示的に使うセットアップ方法も紹介します。
Category: 国際化
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

このウォークスルーでは、小規模なプロジェクトページに英語、スペイン語、フランス語を追加します。サーバーコンポーネント、クライアントコンポーネント、言語切り替え機能を取り上げます。言語の選択にはクッキーを使用します。ロケールのプレフィックス付き URL や多言語 SEO への対応は、別のステップで行います。

General Translation の `gt-next` は Next.js App Router 向けに設計されています。翻訳元のテキストを、その意味を決める JSX 内にそのまま保持し、そのコンテンツを翻訳の生成に結び付けます。曖昧な表現には [`context` プロパティ](/docs/react/reference/components/t#context)で説明を加え、用語やトーンについては[用語集の用語とカスタムプロンプト](/docs/platform/dashboard/guides/defining-context-for-translations)を割り当てます。あとは以下のビルドワークフローによって、翻訳元の変更に合わせて翻訳が更新されます。

## Video

The video is narrated in English, with English captions.

[How do I add i18n to a Next.js app?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-add-i18n-to-nextjs.mp4) (51 秒)

General Translation lets you add i18n with `gt-next`: wrap text in `T` and generate translations. Wrap your config in `withGTConfig`, list your languages, add a `loadTranslations` file, put the `GTProvider` in your root layout, add a `<LocaleSelector>` for the menu, and run `npx gt translate` before `next build`.

## 始める前に

`src/app` ディレクトリを含む既存の TypeScript App Router プロジェクトを用意してください。このページの例は Next.js 16 を対象とし、npm を使用しています。Next.js 16 には Node.js 20.9 以降が必要です。ゼロから始める場合は、まず [Next.js インストールガイド](https://nextjs.org/docs/app/getting-started/installation)の手順に従ってください。Pages Router を使用するアプリについては、[Pages Router クイックスタート](/docs/react/nextjs-pages-router-quickstart)を参照してください。

明示的な設定の例では `gt-next@11.4.12` と `gt@2.26.5` を使用します。このライブラリは MIT ライセンスで提供されており、自分で用意した翻訳であればアカウントなしでレンダリングできます。サービスで翻訳を生成する場合は、GT プロジェクトを作成し、[CLI でログインするか、スコープ付きのツール用キー](/docs/cli/guides/configuring#credentials)を使用してください。自動ビルドでは、CI のシークレットストアに保存したキーを使用してください。

## setup コマンドから始める

アプリディレクトリでセットアップウィザードを実行します。

```bash
npx gt@2.26.5 init
```

App Router アプリ向けの React フレームワークのセットアップ、翻訳元言語と対象言語、ローカル配信か CDN 配信かを選択します。ウィザードは `gt-next` をインストールし、[`GTProvider`](/docs/react/reference/components/gt-provider) と [`withGTConfig`](/docs/react/nextjs/config) を追加したうえで、`gt.config.json` を作成します。ローカル配信を選んだ場合は、翻訳ローダーも作成されます。フレームワークの書き換えは実験的な機能です。生成された差分を、特に既存のプロバイダーや設定のラッパー周辺を中心に確認してください。[セットアップのリファレンス](/docs/cli/reference/commands/init)。

アプリケーションのコンテンツへのマーク付けと翻訳の生成は、引き続きご自身で行う必要があります。検証までの作業をコーディングエージェントに任せたい場合は、[エージェント向けセットアップ](https://generaltranslation.com/agent-prompt.md)を使用してください。

以下の明示的なセットアップでは `src/_gt/[locale].json` を使用します。ウィザードのデフォルトのローカル出力先は `public/_gt/[locale].json` です。生成されたローダーと出力パスはセットのまま使用するか、代替手段として以下の明示的なセットアップをすべて実施してください。

## ライブラリを明示的に設定してページを作成する

### 1. SDK と CLI をインストールする

アプリケーションのディレクトリで、次のコマンドを実行します。

```bash
npm install gt-next@11.4.12
npm install --save-dev gt@2.26.5
```

`gt-next` はアプリケーション内で翻訳をレンダリングします。`gt` はソースコンテンツを収集して翻訳するためのコマンドラインツールです。[Next.js 公式クイックスタート](/docs/react/nextjs-quickstart)

### 2. Next.js と使用する言語を設定する

既存の Next.js の設定を [`withGTConfig`](/docs/react/nextjs/config) でラップします。既存の設定はそのまま残し、すでに使用している他の設定ラッパーがあればそれらと組み合わせてください。

```ts title="next.config.ts"
import { withGTConfig } from 'gt-next/config';

export default withGTConfig({});
```

プロジェクトルートに次のファイルを作成します：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

英語がソース言語、スペイン語とフランス語が対象言語です。出力パスでは、生成された翻訳を CLI が書き込む場所を指定します。

### 3. ローカル翻訳ローダーを追加する

`src/loadTranslations.ts` を作成します。設定プラグインはこのファイルを検出し、生成されたロケールファイルを読み込む際に使用します：

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

このセットアップでは翻訳がアプリケーションにバンドルされるため、本番環境でこのコンテンツのために General Translation へランタイム呼び出しを行う必要はありません。翻訳の更新はビルドに含まれて配信されます。詳しくは[ローカル翻訳の保存](/docs/react/guides/storing-translations)を参照してください。

これらのファイルはまだ存在しません。開発サーバーを起動する前に、ページを完成させてからステップ 6 でファイルを生成してください。そうしないと、ローダーのインポートが失敗する場合があります。

### 4. ルートレイアウトにプロバイダーを追加する

`src/app/layout.tsx` を以下のように変更します。既存のスタイル、フォント、メタデータ、その他のプロバイダーはそのまま残してください。

```tsx title="src/app/layout.tsx"
import type { PropsWithChildren } from 'react';
import { GTProvider } from 'gt-next';
import { getLocale } from 'gt-next/server';

export default async function RootLayout({ children }: PropsWithChildren) {
  const locale = await getLocale();

  return (
    <html lang={locale}>
      <body>
        <GTProvider>{children}</GTProvider>
      </body>
    </html>
  );
}
```

[`getLocale`](/docs/react/nextjs/reference/functions/get-locale) は、サーバー上で現在の言語を解決します。[`GTProvider`](/docs/react/reference/components/gt-provider) は、インタラクティブなコンポーネントを含め、アプリケーションに翻訳コンテキストを提供します。

### 5. JSX と入力属性を翻訳する

次のページを追加します。このページは引き続きサーバーコンポーネントとして動作します。[`T`](/docs/react/reference/components/t) は静的な見出しと段落を翻訳対象としてマークし、[`LocaleSelector`](/docs/react/reference/components/locale-selector) は言語切り替え用のドロップダウンを提供します。

```tsx title="src/app/page.tsx"
import { LocaleSelector, T } from 'gt-next';
import SearchBox from './SearchBox';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <SearchBox />
    </main>
  );
}
```

検索入力欄を クライアントコンポーネント として作成します。プレースホルダーやアクセシビリティ用のラベルなど、文字列を値に取る属性には [`useGT`](/docs/react/reference/hooks/use-gt) を使用します。

```tsx title="src/app/SearchBox.tsx"
'use client';

import { useGT } from 'gt-next';

export default function SearchBox() {
  const gt = useGT();

  return (
    <input
      type='search'
      placeholder={gt('Search projects')}
      aria-label={gt('Search projects')}
    />
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) は翻訳関数を直接返します。非同期のサーバーコンポーネントでは、代わりに `gt-next/server` の [`getGT`](/docs/react/nextjs/reference/functions/get-gt) を使用してください。

[`T`](/docs/react/reference/components/t) の中では、動的な値を生の式のまま記述しないでください。名前、数値、分岐などを含める場合は、適切な[変数コンポーネントとフォーマット用コンポーネント](/docs/react/guides/formatting-variables)を使用してください。

## 翻訳を生成して結果を確認する

### 6. 翻訳済みの出力を生成する

自動翻訳を利用するには、[`gt login`](/docs/cli/reference/commands/login) でサインインしてプロジェクトIDを設定するか、プロジェクトのAPIキーとプロジェクトIDを `.env.local` に記述します。

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="your-project-api-key"
```

キーは外部に公開せず、ファイルもソース管理に含めないでください。`GT_API_KEY` を `NEXT_PUBLIC_` 変数経由で公開しないでください。ツール用のキーには、ファイルの読み書き権限と翻訳キューの権限が必要です。文脈を使用する場合は、文脈へのアクセス権限も必要です。詳しくは [APIキーのドキュメント](/docs/platform/dashboard/reference/api-keys)を参照してください。

翻訳を生成します：

```bash
npx gt translate
```

このコマンドは翻訳ジョブを General Translation に送信し、設定された出力パスにロケールファイルを書き出します。生成されたテキストは [ダッシュボードの翻訳エディター](/docs/platform/dashboard/guides/reviewing-translations) で確認できます。ダウンロードした翻訳をローカルで編集した場合は、[`gt save-local`](/docs/cli/reference/commands/save-local) を使ってその修正内容をプラットフォームに同期できます。サービスによる生成には [従量課金](https://generaltranslation.com/pricing) が適用されます。

翻訳サービスを呼び出さずにライブラリを試したい場合は、代わりに次のコマンドを実行してください：

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) は原文を含むテンプレートを作成するだけで、**テキストの翻訳は行いません**。`src/_gt/es.json` と `src/_gt/fr.json` のテキスト値を、生成されたキーと JSX 構造を保ったまま編集してください。たとえば、スペイン語の見出しは「Encuentra tu próximo proyecto」、検索ラベルは「Buscar proyectos」と翻訳します。これらのファイルを完成版として扱う前に、残りのテキストもすべて翻訳してください。

ソースコンテンツを変更したら、[`gt generate`](/docs/cli/reference/commands/generate) を再実行してターゲットファイルを確認してください。このコマンドは既存のターゲット値を保持したまま、新しいエントリを原文のまま追加し、翻訳元から削除されたエントリを取り除きます。

### 7. アプリを起動して言語を切り替える

```bash
npm run dev
```

Next.js が表示したアドレスを開きます。ドロップダウンでスペイン語とフランス語を選択し、見出し、段落、プレースホルダー、およびアクセシブルな入力ラベルが切り替わることを確認してください。ページを再読み込みして選択した言語が保持されていることを確認したら、英語に戻します。

セレクターは切り替わるのにテキストが英語のままの場合は、翻訳先言語のファイルを確認してください。[`gt generate`](/docs/cli/reference/commands/generate) で生成されたソーステンプレートは、翻訳するまで英語のままです。ロケールファイルが見つからずページのコンパイルに失敗する場合は、該当する生成コマンドを再実行してから開発サーバーを再起動してください。

## 本番環境向けにビルドする

ホスト型の翻訳リクエストを送信する前に [`gt validate`](/docs/cli/reference/commands/validate) を実行し、翻訳の構文エラーを検出してください。GT の [ESLint ルール](/docs/react/guides/linting-your-code)を使えば、開発中に追加のチェックも行えます。また、[開発時の翻訳を設定](/docs/react/guides/configuring#delivery)しておけば、編集しながら翻訳済みコンテンツをプレビューできます。

自動翻訳ワークフローを利用する場合は、次のビルドコマンドを既存の `package.json` の scripts にマージしてください：

```json
{
  "scripts": {
    "build": "gt validate && gt translate && next build"
  }
}
```

ビルド環境で `GT_PROJECT_ID` と `GT_API_KEY` を設定します。開発依存関係としてインストールした CLI が、ビルド時に利用できることを確認してください。ビルドのたびに翻訳出力を再生成する場合は、`src/_gt/` を `.gitignore` に追加します。

手動翻訳を選択した場合は、翻訳済みファイルをバージョン管理に含めるか、独自の翻訳パイプラインから取得してください。これらのファイルが揃ってから `next build` を実行します。手動で管理している翻訳を再生成可能な出力として無視すると、唯一のコピーが失われるおそれがあるため注意してください。

ビルド後、本番環境のアプリを起動し、言語切り替えをもう一度確認します。開発環境での動作だけに頼らず、実際にリリースされるファイルをテストできます。

[インクリメンタルな翻訳ワークフロー](/docs/cli/guides/generating-translations#retranslate)では、変更された翻訳元のみを翻訳し、以前のバージョンからマッチングする翻訳を再利用します。リポジトリの変更も自動化したい場合は、[Locadex](/docs/platform/locadex/guides/configuring-automations) を設定すると、新しい UI の国際化、翻訳の生成、ロケール変更の同期をプルリクエスト経由で行えます。トリガーとレビューの設定は、リリースプロセスに合わせて選択してください。

アプリケーションを再ビルドせずに翻訳を更新したい場合は、ローカルのローダーではなく [CDN 配信](/docs/react/nextjs/config)を選択します。公開した翻訳の編集内容が、バージョンとキャッシュの設定に従ってデプロイ済みのアプリケーションに反映されるようになります。

言語ごとに別々の URL が必要な公開ページについては、[App Router のロケールルーティング](/docs/react/nextjs/app-router-middleware)に進んでください。ここで紹介したクッキーベースの例では、`/es` や `/fr` のページは作成されず、カノニカル URL や `hreflang` メタデータも設定されません。

## コーディングエージェント向けのプロンプト

まず、継続的に更新されている[公式セットアッププロンプト](https://generaltranslation.com/agent-prompt.md)をベースにし、次の機能概要を追記してください。

```text
英語をソース言語とし、スペイン語とフランス語を翻訳先言語にしてください。
ローカルにバンドルされた翻訳を使って、プロジェクトページをローカライズしてください。
既存のプロバイダーとルートはそのまま維持してください。見出し、段落、検索入力欄、
アクセシブルラベル、言語セレクターを含めてください。用語はプロジェクト共通のものを使用してください。
言語の切り替え、再読み込み後の設定保持、サーバーでレンダリングされたコンテンツ、
クライアント側の属性、本番環境ビルドを検証してください。実際にテストした内容と、
言語面のレビューがまだ必要な箇所を報告してください。デプロイやマージは行わないでください。
```

ワークフロー全体については、[翻訳ファイルを使わない i18n](/kb/i18n-without-translation-files)と[コーディングエージェントの活用](/kb/ai-agent-i18n-setup)を参照してください。

## Related questions

- [翻訳ファイルなしでi18nは実現できますか？](https://generaltranslation.com/ja/kb/i18n-without-translation-files.mdx): はい。General Translationの gt-react と gt-next ライブラリを使えば、翻訳キーも、言語ごとに管理するJSONファイルもなしで、ReactとNext.jsのi18nを実現できます。文言は `<T>` コンポーネント内のJSXにインラインで記述したままで、gt translate コマンドがコードから得た文脈をもとに、ビルド時に各言語の翻訳を生成します。さらにLocadexを使えば、プルリクエストを通じて翻訳を常に最新の状態に保てます。
- [Cursor や Claude Code でアプリを国際化するには？](https://generaltranslation.com/ja/kb/ai-agent-i18n-setup.mdx): Cursor または Claude Code で General Translation の Setup for Agents プロンプトを使い、機能と対象言語を選んで、エージェントに実装と検証を任せます。ブラウザでのサインイン、機械可読なドキュメント、MCP ツールにより、セットアップから翻訳、レビューまでがシームレスにつながります。継続的なローカライゼーションは、Locadex を使ってプルリクエスト経由で自動化できます。
- [デプロイのたびに翻訳を最新の状態に保つにはどうすればよいですか？](https://generaltranslation.com/ja/kb/translations-in-ci.mdx): 本番環境のビルド前に、翻訳をパイプラインのステップとして毎回実行します。こうすることで、新しいテキストは追加されたデプロイと同時に翻訳済みの状態でリリースされます。General Translation の gt CLI では、CI シークレットとして保存したプロジェクトの APIキーとプロジェクトIDを使い、npx gt translate でこれを実現します。

## Previous and next questions

- Previous question: [Mintlify のドキュメントサイトを翻訳するには？](https://generaltranslation.com/ja/kb/translate-mintlify-docs.mdx)
- Next question: [Node.js アプリを翻訳するには？](https://generaltranslation.com/ja/kb/translate-node-app.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/ja/kb/sitemap.md) for every article.