# General Translation React SDKs (gt-react, gt-next): 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 クイックスタート このガイドを終える頃には、Next.js Pages Router アプリで複数の言語のコンテンツを表示でき、ユーザーが操作できる言語切り替え機能も実装できるようになります。 Pages Router では、`gt-next` は `getServerSideProps` を介して動作します。リクエストごとにサーバーがユーザーのロケールを判定し、翻訳スナップショットを読み込んで、その両方を `_app.tsx` の `` に渡すため、初回レンダリング時にはすでに翻訳済みの内容が表示されます。 `gt-next/server` エントリは App Router 専用で、Pages Router では動作しません。 **前提条件:** * **Pages Router** を使用する Next.js アプリ * Node.js 18+ **注:** App Router を使用している場合は、代わりに [Next.js App Router クイックスタート](/docs/react/nextjs-quickstart) を参照してください。こちらはサーバーコンポーネントを使用するため、`getServerSideProps` の設定は不要です。 ## クイックスタート [#quickstart] ### 1. パッケージをインストールする `gt-next` は、アプリで翻訳を機能させるライブラリです。`gt` は、本番環境向けに翻訳を準備する CLI ツールです。 ```bash npm i gt-next npm i -D gt ``` ```bash yarn add gt-next yarn add --dev gt ``` ```bash bun add gt-next bun add --dev gt ``` ```bash pnpm add gt-next pnpm add --save-dev gt ``` ### 2. Next.js の設定を行う `gt-next` は、ビルド時に国際化を設定するための Next.js プラグイン **`withGTConfig`** を使用します。既存の Next.js 設定をこれでラップしてください: ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; const nextConfig = {}; export default withGTConfig(nextConfig); ``` このプラグインは翻訳設定を読み取り、裏側ですべてを自動的に連携します。ロケールのプレフィックスが付いたURLについては、[Pages Router ミドルウェアガイド](/docs/react/nextjs/pages-router-middleware)を参照してください。 ### 3. 翻訳設定ファイルを作成する プロジェクトのルートに **`gt.config.json`** ファイルを作成します。これにより、サポートする言語をライブラリに指定します。 ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr", "ja"], "files": { "gt": { "output": "public/_gt/[locale].json" } } } ``` * **`defaultLocale`** — アプリの記述に使う言語 (ソース言語) 。 * **`locales`** — 翻訳先の言語。[サポートされているロケールの一覧](/docs/platform/dashboard/reference/supported-locales) から任意に選択します。 * **`files.gt.output`** — CLI が翻訳ファイルを保存する場所です。`[locale]` は各言語コード (例: `public/_gt/es.json`) に置き換えられます。 **`.gitignore`** に `public/_gt/` を追加してください。これらのファイルは手書きではなく、自動生成されます。 ```txt title=".gitignore" public/_gt/ ``` ### 4. ローカル翻訳用のロード関数を追加する プロジェクトのルート (または `src/` ディレクトリ) に **`loadTranslations`** ファイルを作成します。これにより、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 {}; } } ``` `withGTConfig` は、プロジェクトのルートまたは `src/` ディレクトリにある `loadTranslations.[js|ts]` ファイルを自動的に検出するため、追加の設定は不要です。 **注:** ローカル翻訳 はアプリにバンドルされるため、外部サービスに依存せず即座に読み込まれます。詳しくは、[翻訳の保存](/docs/react/guides/storing-translations) を参照してください。メリットとトレードオフも説明しています。 ### 5. 各ページで getServerSideProps をラップする 各ページの `getServerSideProps` を **`withGTServerSideProps`** でラップします。リクエストごとに、設定されていれば `generaltranslation.locale` cookie、そうでなければ `Accept-Language` header からユーザーのロケールを特定し、そのロケール用の翻訳スナップショットを読み込んで、両方をページの 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`** コンポーネントを使うと、アプリ全体で翻訳を利用できるようになります。`_app.tsx` では、`pageProps` から注入された props を取り出して provider に渡します。**`WithGTServerSideProps`** 型は、注入されるデータの形を表します。 ```tsx title="pages/_app.tsx" import type { AppProps } from 'next/app'; import { GTProvider, WithGTServerSideProps } from 'gt-next'; export default function App({ Component, pageProps, }: AppProps) { const { locale, translations, ...restPageProps } = pageProps; return ( ); } ``` ロケールと翻訳はサーバーのレスポンスとともに届くため、初回レンダリングの時点ですでにユーザーの言語で表示されます — クライアント側の読み込み状態はありません。 ### 7. 翻訳対象としてコンテンツをマークする 次に、翻訳したいテキストを **``** コンポーネントで囲みます。`` は "translate" を意味します: ```tsx title="pages/index.tsx" import { T } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.
); } ``` `` の中では、必要に応じて JSX を好きな範囲で囲めます。中にあるものは、テキスト、入れ子になった要素、書式設定も含めて、すべてひとまとまりの単位として翻訳されます。 ### 8. 言語切り替え機能を追加する ユーザーが言語を切り替えられるよう、**``** を追加します： ```tsx title="pages/index.tsx" import { T, LocaleSelector } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.
); } ``` `LocaleSelector` は、`gt.config.json` に含まれる言語を一覧表示するドロップダウンをレンダリングします。ユーザーが言語を選択すると、`gt-next` はその選択を `generaltranslation.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/signup) で無料のキーを取得するか、次を実行してください: ```bash npx gt auth ``` **警告:** 開発環境では、`gtx-dev-` で始まるキーを使用してください。本番用キー (`gtx-api-`) は CI/CD でのみ使用します。 `GT_API_KEY` をブラウザに公開したり、ソース管理にコミットしたりしないでください。 ### 10. 動作を確認する 開発サーバーを起動します。 ```bash npm run dev ``` ```bash yarn dev ``` ```bash bun dev ``` ```bash pnpm dev ``` [http://localhost:3000](http://localhost:3000) を開き、言語 dropdown で言語を切り替えます。コンテンツが翻訳されて表示されることを確認してください。 **注:** 開発環境では、翻訳は on-demand で行われるため、新しい言語に初めて切り替えたときに短い読み込み状態が表示されることがあります。本番環境では、翻訳は事前生成されるため、すぐに読み込まれます。 ### 11. 文字列も翻訳する (JSX だけでなく) `placeholder` 属性、`aria-label` の値、`alt` テキストのようなプレーンな文字列には、**`useGT`** フックを使用します。 ```tsx title="pages/contact.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return (
); } ``` ### 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 ``` **警告:** 本番用キーは `gtx-api-` で始まります (`gtx-dev-` ではありません) 。[dash.generaltranslation.com](https://dash.generaltranslation.com) で取得してください。`NEXT_PUBLIC_` を先頭に付けないでください。 これで完了です。アプリは多言語対応になりました。🎉 ## トラブルシューティング [#troubleshooting] はい — `` には `locale` と `translations` の props が必要で、これらは `getServerSideProps` をラップしたページでしか利用できません。独自にデータを取得しないページでは、引数なしの形式を export してください。 ```tsx export const getServerSideProps = withGTServerSideProps(); ``` はい。ページを `withGTStaticProps` でラップし、生成された props を `_app.tsx` 内の `GTProvider` に引き続き渡してください。セットアップ全体については、[Pages Router の静的サイト生成ガイド](/docs/react/nextjs/pages-router-static-site-generation)を参照してください。 `gt-next` は、`generaltranslation.locale` という cookie にユーザーの言語設定を保存します。以前に別の言語でテストしていた場合、この cookie が選択内容より優先されることがあります。クッキーを削除して、もう一度試してください。 * [Chrome](https://support.google.com/chrome/answer/95647) * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored) * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0) これは想定どおりの動作です。開発環境では、翻訳はオンデマンドで行われます (コンテンツは API 経由でリアルタイムに翻訳されます) 。この遅延は**本番環境では発生しません** — すべての翻訳は `npx gt translate` によって事前生成されます。 ## Next steps - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables