# General Translation React SDKs (gt-react, gt-next, gt-react-native): Next.js Pages Router クイックスタート
URL: https://generaltranslation.com/ja/docs/react/nextjs-pages-router-quickstart.mdx
---

title: Next.js Pages Router クイックスタート
description: General Translation を使って、10 分以内に Next.js Pages Router アプリに複数の言語を追加できます。
related:
  links:
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/managing-locales
    - /docs/react/guides/formatting-variables

---

このガイドを終える頃には、Next.js Pages Router アプリで複数の言語のコンテンツを表示でき、ユーザーが操作できる言語切り替え機能も実装できるようになります。

Pages Router では、`gt-next` は `getServerSideProps` を介して動作します。リクエストごとにサーバーがユーザーのロケールを判定し、翻訳スナップショットを読み込んで、その両方を `_app.tsx` の [`<GTProvider>`](/docs/react/reference/components/gt-provider) に渡すため、初回レンダリング時にはすでに翻訳済みの内容が表示されます。

`gt-next/server` エントリは App Router 専用で、Pages Router では動作しません。

**前提条件:**

* **Pages Router** を使用する Next.js アプリ
* Node.js 18+

<Callout type="info">
  **注:** App Router を使用している場合は、代わりに [Next.js App Router クイックスタート](/docs/react/nextjs-quickstart) を参照してください。こちらはサーバーコンポーネントを使用するため、`getServerSideProps` の設定は不要です。
</Callout>

## クイックスタート [#quickstart]

### 1. パッケージをインストールする

`gt-next` は、アプリで翻訳を機能させるライブラリです。`gt` は、本番環境向けに翻訳を準備する CLI ツールです。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-next
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-next
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-next
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-next
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 2. 翻訳設定ファイルを作成する

プロジェクトのルートに **`gt.config.json`** ファイルを作成します。これにより、サポートする言語をライブラリに指定します。

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

* **`defaultLocale`** — アプリの記述に使う言語 (ソース言語) 。
* **`locales`** — アプリで利用可能なすべてのロケール。Next.js の国際化ルーティングでは `defaultLocale` が必要なため含めたうえで、翻訳先の言語を追加します。[サポートされているロケールの一覧](/docs/platform/dashboard/reference/supported-locales) から任意に選択します。
* **`files.gt.output`** — CLI が翻訳ファイルを保存する場所です。`[locale]` は各言語コード (例: `public/_gt/es.json`) に置き換えられます。

**`.gitignore`** に `public/_gt/` を追加してください。これらのファイルは手書きではなく、自動生成されます。

```txt title=".gitignore"
public/_gt/
```

### 3. Next.js の国際化ルーティングを設定する

Pages Router では、ロケールプレフィックス付き URL とリクエストロケールの検出に [Next.js internationalized routing](https://nextjs.org/docs/pages/guides/internationalization) を使用します。ロケール設定を `next.config.ts` にインポートし、config を `withGTConfig` でラップします。

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

const nextConfig: NextConfig = {
  i18n: {
    locales: gtConfig.locales,
    defaultLocale: gtConfig.defaultLocale,
  },
};

export default withGTConfig(nextConfig);
```

Next.js では、デフォルトロケールは `/` のままとし、`/es` や `/fr` などの他のロケールにはプレフィックスを付けます。`gt-next` ミドルウェアや `pages/[locale]` のルートセグメントは必要ありません。検出と移行の詳細については、[Pages Router のロケールルーティング](/docs/react/nextjs/pages-router-middleware)を参照してください。

### 4. ローカル翻訳用のロード関数を追加する

プロジェクトのルート (または `src/` ディレクトリ) に **[`loadTranslations`](/docs/react/reference/functions/load-translations)** ファイルを作成します。これにより、CLI によって生成された翻訳ファイルを `gt-next` がどのように読み込むかを指定できます。

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

<Callout type="info">
  **注:** これらの翻訳ファイルは、[`npx gt generate`](/docs/cli/reference/commands/generate) (API キー 不要) または [`npx gt translate`](/docs/cli/reference/commands/translate) (credentials あり) で作成するまで存在しません。それまでは、`public/_gt` ディレクトリが見つからないという警告が bundler によって表示され、上記の `try`/`catch` は `{}` を返すため、アプリは未翻訳のコンテンツのままでも引き続き動作します。
</Callout>

`withGTConfig` は、プロジェクトのルートまたは `src/` ディレクトリにある `loadTranslations.[js|ts]` ファイルを自動的に検出するため、追加の設定は不要です。

<Callout type="info">
  **注:** ローカル翻訳 はアプリにバンドルされるため、外部サービスに依存せず即座に読み込まれます。詳しくは、[翻訳の保存](/docs/react/guides/storing-translations) を参照してください。メリットとトレードオフも説明しています。
</Callout>

### 5. 各ページで getServerSideProps をラップする

各ページの `getServerSideProps` を **`withGTServerSideProps`** でラップします。リクエストごとに、Next.js が `context.locale` に解決したロケールを読み取り、そのロケール用の翻訳スナップショットを読み込んで、両方をページの props に注入します。

```tsx title="pages/index.tsx"
import type { GetServerSideProps } from 'next';
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps: GetServerSideProps = withGTServerSideProps(
  async (context) => {
    return {
      props: {
        // 独自のprops
      },
    };
  }
);
```

ページで独自のサーバーサイドpropsが不要な場合は、引数なしで呼び出します:

```tsx title="pages/about.tsx"
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps = withGTServerSideProps();
```

`withGTServerSideProps` は、`locale` と `translations` を props に追加します (内部の `enableI18n` フラグも追加されます) 。内部関数が `redirect` または `notFound` を返した場合は、翻訳を読み込まず、その結果を変更せずにそのまま返します。

### 6. GTProvider をアプリに追加する

**[`GTProvider`](/docs/react/reference/components/gt-provider)** コンポーネントを使うと、アプリ全体で翻訳を利用できるようになります。`_app.tsx` では、`pageProps` から注入された props を取り出して provider に渡します。**`WithGTServerSideProps`** 型は、注入されるデータの形を表します。

```tsx title="pages/_app.tsx"
import type { AppProps } from 'next/app';
import Router from 'next/router';
import { GTProvider, type WithGTServerSideProps } from 'gt-next';

export default function App({
  Component,
  pageProps,
}: AppProps<WithGTServerSideProps>) {
  const { locale, translations } = pageProps;

  return (
    <GTProvider
      locale={locale}
      translations={translations}
      _reload={({ locale: nextLocale }) => {
        void Router.push(Router.pathname, Router.asPath, {
          locale: nextLocale,
        });
      }}
    >
      <Component {...pageProps} />
    </GTProvider>
  );
}
```

ロケールと翻訳はサーバーのレスポンスとともに届くため、初回レンダリングの時点ですでにユーザーの言語で表示されます — クライアント側の読み込み状態はありません。`_reload` コールバックはロケールの変更を Next.js ルーターに渡し、選択したロケールのページ props を読み込ませます。

### 7. 翻訳対象としてコンテンツをマークする

次に、翻訳したいテキストを **[`<T>`](/docs/react/reference/components/t)** コンポーネントで囲みます。[`<T>`](/docs/react/reference/components/t) は &quot;translate&quot; を意味します:

```tsx title="pages/index.tsx"
import { T } from 'gt-next';

export default function Home() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

[`<T>`](/docs/react/reference/components/t) の中では、必要に応じて JSX を好きな範囲で囲めます。中にあるものは、テキスト、入れ子になった要素、書式設定も含めて、すべてひとまとまりの単位として翻訳されます。

### 8. 言語切り替え機能を追加する

ユーザーが言語を切り替えられるよう、**[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)** を追加します：

```tsx title="pages/index.tsx"
import { T, LocaleSelector } from 'gt-next';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

[`LocaleSelector`](/docs/react/reference/components/locale-selector) は、`gt.config.json` に含まれる言語を一覧表示するドロップダウンをレンダリングします。ユーザーが言語を選択すると、`_app.tsx` のコールバックがローカライズされたURLへ移動し、Next.jsがその選択を `NEXT_LOCALE` cookie に保存します。次にサーバーが選択されたロケールをレンダリングします。

### 9. 環境変数を設定する (任意)

開発中に翻訳を確認するには、General Translation の API キーが必要です。これにより **オンデマンド翻訳** が有効になり、開発しながらアプリのコンテンツをリアルタイムで翻訳できるようになります。

**`.env.local`** ファイルを作成します:

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

[dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) で無料のキーを取得するか、次を実行してください:

```bash
npx gt auth
```

<Callout type="warn">
  **警告:** 開発環境では、`gtx-dev-` で始まるキーを使用してください。本番用キー (`gtx-api-`) は CI/CD でのみ使用します。

  `GT_API_KEY` をブラウザに公開したり、ソース管理にコミットしたりしないでください。
</Callout>

### 10. 動作を確認する

開発サーバーを起動します。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

[http://localhost:3000](http://localhost:3000) を開き、言語 dropdown で言語を切り替えます。コンテンツが翻訳されて表示されることを確認してください。

<Callout type="info">
  **注:** 開発環境では、翻訳は on-demand で行われるため、新しい言語に初めて切り替えたときに短い読み込み状態が表示されることがあります。本番環境では、翻訳は事前生成されるため、すぐに読み込まれます。
</Callout>

### 11. 文字列も翻訳する (JSX だけでなく)

`placeholder` 属性、`aria-label` の値、`alt` テキストのようなプレーンな文字列には、**[`useGT`](/docs/react/reference/hooks/use-gt)** フックを使用します。

```tsx title="pages/contact.tsx"
import { useGT } from 'gt-next';

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

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}
```

### 12. 本番環境にデプロイする

本番環境では、翻訳はビルド時に事前生成されるため、リアルタイムのAPI呼び出しは発生しません。ビルドスクリプトにtranslateコマンドを追加します。

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && next build"
  }
}
```

ホスティングサービス (Vercel、Netlify など) で、**本番**用の環境変数を設定します。

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  **警告:** 本番用キーは `gtx-api-` で始まります (`gtx-dev-` ではありません) 。[dash.generaltranslation.com](https://dash.generaltranslation.com) で取得してください。`NEXT_PUBLIC_` を先頭に付けないでください。
</Callout>

これで完了です。アプリは多言語対応になりました。🎉

## トラブルシューティング [#troubleshooting]

<Accordions>
  <Accordion title="すべてのページで withGTServerSideProps が必要ですか？">
    はい — [`<GTProvider>`](/docs/react/reference/components/gt-provider) には `locale` と `translations` の props が必要で、これらは `getServerSideProps` をラップしたページでしか利用できません。独自にデータを取得しないページでは、引数なしの形式を export してください。

    ```tsx
    export const getServerSideProps = withGTServerSideProps();
    ```
  </Accordion>

  <Accordion title="代わりに getStaticProps を使えますか？">
    はい。ページを `withGTStaticProps` でラップし、生成された props を `_app.tsx` 内の [`GTProvider`](/docs/react/reference/components/gt-provider) に引き続き渡してください。セットアップ全体については、[Pages Router の静的サイト生成ガイド](/docs/react/nextjs/pages-router-static-site-generation)を参照してください。
  </Accordion>

  <Accordion title="ドロップダウンを使っても言語が切り替わりません">
    上記のとおり、`_reload` が選択した `locale` オプションを指定して `Router.push` を呼び出していることを確認してください。選択後、URL にはロケールプレフィックスが使用され、`NEXT_LOCALE` cookie にはそのロケールが含まれているはずです。
  </Accordion>

  <Accordion title="開発環境では翻訳が遅いです">
    これは想定どおりの動作です。開発環境では、翻訳はオンデマンドで行われます (コンテンツは API 経由でリアルタイムに翻訳されます) 。この遅延は**本番環境では発生しません** — すべての翻訳は [`npx gt translate`](/docs/cli/reference/commands/translate) によって事前生成されます。
  </Accordion>
</Accordions>
## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables