# General Translation React SDKs (gt-react, gt-next): Next.js App Router クイックスタート URL: https://generaltranslation.com/ja/docs/react/nextjs-quickstart.mdx --- title: Next.js App Router クイックスタート description: General Translation を使えば、10 分以内に Next.js App 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 App Router クイックスタートこのガイドを読み終える頃には、Next.js アプリで複数の言語のコンテンツを表示し、ユーザーが操作できる言語切り替え機能を実装できるようになります。 **前提条件:** * **App Router** を使用する Next.js アプリ (Next.js 13 以降) * Node.js 18 以降 **ヒント:** `npx gt@latest` を実行すると、[セットアップウィザード](/docs/cli/reference/commands/init) ですべて設定できます。このガイドでは手動でのセットアップ方法を説明します。 **注意:** Pages Router を使用している場合は、代わりに [Next.js Pages Router クイックスタート](/docs/react/nextjs-pages-router-quickstart) を参照してください。 ## クイックスタート [#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); ``` このプラグインは翻訳設定を読み込み、裏側ですべてを自動的に連携します。Next.js の設定にほかの変更は必要ありません。 ### 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. ローカル翻訳用の load 関数を追加する `src/` ディレクトリ (またはプロジェクトルート) に **`loadTranslations`** ファイルを作成します。これにより、CLI が生成した翻訳ファイルを `gt-next` がどのように読み込むかを指定できます。 ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`../public/_gt/${locale}.json`); return translations.default; } ``` `withGTConfig` は、`src/` ディレクトリまたはプロジェクトルートにある `loadTranslations.[js|ts]` ファイルを自動的に検出するため、追加の設定は不要です。 **注:** ローカル翻訳はアプリにバンドルされるため、外部サービスに依存せず即座に読み込まれます。詳しい内容とトレードオフについては、[翻訳の保存](/docs/react/guides/storing-translations) を参照してください。 ### 5. レイアウトに GTProvider を追加する **`GTProvider`** コンポーネントを使うと、アプリ全体で翻訳を利用できるようになります。アプリを `root layout` レベルでラップする必要があります。 ```tsx title="app/layout.tsx" import { GTProvider, useLocale } from 'gt-next'; export default function RootLayout({ children }: { children: React.ReactNode }) { const locale = useLocale(); return ( {children} ); } ``` ### 6. 翻訳対象としてコンテンツをマークする次に、翻訳したいテキストを **``** コンポーネントで囲みます。`` は "translate" の略です: ```tsx title="app/page.tsx" import { T } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.

); } ``` `` の中には、必要に応じて JSX を多くも少なくも含められます。中身は、テキスト、ネストした要素、書式設定も含めて、すべてひとまとまりで翻訳されます。 ### 7. 言語切り替え機能を追加するユーザーが言語を切り替えられるよう、**``** を追加します: ```tsx title="app/page.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` の言語が設定されたドロップダウンを表示します。 ### 8. 環境変数を設定する (任意) 開発中に翻訳を表示するには、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` をブラウザに公開したり、ソース管理にコミットしたりしないでください。はい。API キーがなくても、`gt-next` は標準的な i18n ライブラリとして動作します。開発時にオンデマンド翻訳は利用できませんが、次のことは引き続き可能です。 * 独自の翻訳ファイルを手動で用意する * すべてのコンポーネント (``、``、`LocaleSelector` など) を使用する * `npx gt generate` を実行して翻訳ファイルのテンプレートを作成し、その後自分で翻訳する ### 9. 動作を確認する開発サーバーを起動します。 ```bash npm run dev ``` ```bash yarn dev ``` ```bash bun dev ``` ```bash pnpm dev ``` [http://localhost:3000](http://localhost:3000) を開き、言語 dropdown で言語を切り替えます。コンテンツが翻訳されていることを確認できます。 **注:** 開発環境では、翻訳は on-demand で行われるため、新しい言語に初めて切り替えると、短時間読み込み状態が表示されることがあります。Production では、翻訳は pre-generated されるため、すぐに読み込まれます。 ### 10. 文字列を翻訳する `placeholder` 属性、`aria-label` の値、`alt` テキストのようなプレーンな文字列には、**`useGT`** フックを使用します。これは、同期的なサーバーコンポーネントとクライアントコンポーネントの両方で動作します。 ```tsx title="app/contact/page.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return ( ); } ``` 非同期コンポーネントでは hooks は使えません。代わりに `gt-next/server` から `getGT` をインポートしてください。 ```tsx import { getGT } from 'gt-next/server'; export default async function Page() { const gt = await getGT(); return

{gt('Hello')}

; } ``` ### 11. 本番環境にデプロイする本番環境では、翻訳はビルド時に事前生成されるため、リアルタイムの 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] `gt-next` は、ユーザーの言語設定を `generaltranslation.locale` という名前の cookie に保存します。以前に別の言語でテストしたことがある場合、この 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) これは想定どおりの動作です。開発環境では、翻訳は on-demand で行われます (コンテンツは API 経由でリアルタイムに翻訳されます) 。この遅延は **本番環境では発生しません**。すべての翻訳は `npx gt translate` によって事前生成されます。あいまいなテキストは、不正確な翻訳の原因になることがあります。たとえば、"apple" は果物を指す場合もあれば、会社を指す場合もあります。意味を明確にするために `context` prop を追加してください。 ```jsx Apple ``` ``、`useGT()`、`getGT()` はいずれも `context` オプションに対応しています。 ## Next steps - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables