# gt-next: General Translation Next.js SDK: Pages Router クイックスタート URL: https://generaltranslation.com/ja/docs/next/tutorials/quickstart-pages-router.mdx --- title: Pages Router クイックスタート description: 10分以内で Next.js Pages Router アプリに複数言語を追加 --- このガイドを終える頃には、Next.js Pages Router アプリでコンテンツを複数の言語で表示できるようになり、ユーザーが操作できる言語切り替え機能も利用できるようになります。 Pages Router では、`gt-next` は `getServerSideProps` を通じて動作します。各リクエストでサーバーがユーザーのロケールを判定し、翻訳スナップショットを読み込んで、その両方を `_app.tsx` の `` に渡すため、初回レンダリング時にはすでに翻訳済みの状態になります。 **前提条件:** * **Pages Router** を使用している Next.js アプリ * Node.js 18+ **App Router を使っていますか？** その場合は [Next.js クイックスタート](/docs/next) を参照してください。こちらはサーバーコンポーネントを使用するため、`getServerSideProps` の設定は不要です。 *** ## ステップ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` は、ビルド時に国際化を設定するための **`withGTConfig`** という Next.js プラグインを使用します。既存の Next.js 設定をこれでラップしてください。 ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; const nextConfig = {}; export default withGTConfig(nextConfig); ``` このプラグインは翻訳の設定を読み取り、裏側で必要な処理をまとめて行います。設定内容は App Router と Pages Router で共通のため、ルーター固有のフラグは不要です。 *** ## ステップ 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/supported-locales)から任意のものを選んでください。 * **`files.gt.output`** — CLI が翻訳ファイルを保存する場所です。`[locale]` は各言語コード (例: `public/_gt/es.json`) に置き換えられます。 **`.gitignore`** に `public/_gt/` を追加してください — これらのファイルは手動で作成するものではなく、自動生成されます: ```txt title=".gitignore" public/_gt/ ``` *** ## ステップ4: ローカル翻訳用の load 関数を追加する プロジェクトルート (または `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/next/guides/local-tx) をご覧ください。 *** ## ステップ 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` は、props に `locale` と `translations` (および内部フラグの `enableI18n`) を追加します。内部関数が `redirect` または `notFound` を返した場合は、翻訳を読み込まず、その結果をそのまま返します。 *** ## ステップ6: アプリに GTProvider を追加する **`GTProvider`** コンポーネントを使うと、アプリ全体で翻訳を利用できるようになります。`_app.tsx` では、`pageProps` から注入された props を取り出して `GTProvider` に渡します。**`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 で行われるため、新しい言語に初めて切り替えた際に短時間の読み込み状態が発生することがあります。Production では翻訳が事前生成されるため、すぐに読み込まれます。 *** ## ステップ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 ``` Production keys は `gtx-api-` で始まります (`gtx-dev-` ではありません) 。[dash.generaltranslation.com](https://dash.generaltranslation.com) から取得してください。`NEXT_PUBLIC_` を先頭に付けないでください。 これで完了です。アプリは多言語対応になりました。🎉 *** ## トラブルシューティング はい。`` には `locale` と `translations` の props が必要で、これらは `getServerSideProps` をラップしたページでのみ利用できます。ページ側で独自にデータ取得を行わない場合は、引数なしの形式を export してください。 ```tsx export const getServerSideProps = withGTServerSideProps(); ``` いいえ。ロケールの解決にはリクエストごとのデータ (ロケールのクッキーと `Accept-Language` ヘッダー) が必要ですが、これは静的生成時には利用できません。`gt-next` は Pages Router 向けの `getStaticProps` ヘルパーを提供していません。 `gt-next` は、ユーザーの言語設定を `generaltranslation.locale` というクッキーに保存します。以前に別の言語でテストしていた場合、このクッキーが選択内容より優先されることがあります。クッキーを削除して、もう一度お試しください。 * [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` によって事前生成されます。 *** ## 次のステップ * [**`` コンポーネントガイド**](/docs/next/guides/t) — 変数、複数形、さらに高度な翻訳パターンについて学びます * [**文字列翻訳ガイド**](/docs/next/guides/strings) — `useGT` を詳しく学びます * [**変数コンポーネント**](/docs/next/guides/variables) — ``、``、``、`` を使って動的コンテンツを扱います * [**複数形対応**](/docs/next/api/components/plural) — `` コンポーネントで複数形を扱います * [**本番環境へのデプロイ**](/docs/next/tutorials/quickdeploy) — CI/CD のセットアップ、キャッシュ、パフォーマンス最適化 * [**共有文字列**](/docs/next/guides/shared-strings) — 配列、設定オブジェクト、共有データ内のテキストを `msg()` で翻訳します