# General Translation React SDKs (gt-react, gt-next, gt-react-native): Next.js App Router クイックスタート URL: https://generaltranslation.com/ja/docs/react/nextjs-quickstart.mdx Docs index: https://generaltranslation.com/llms.txt Description: 10 分以内で、General Translation を使って Next.js App Router アプリに複数の言語を追加します。このガイドを読み終える頃には、Next.js アプリで複数の言語のコンテンツを表示し、ユーザーが操作できる言語切り替え機能を実装できるようになります。 **前提条件:** * **App Router** を使用する Next.js アプリ (Next.js 13.0.0 以降、15.2.1 および 15.2.2 を除く) * Node.js 18 以降 **ヒント:** `npx gt@latest` を実行すると、[セットアップウィザード](/docs/cli/quickstart) ですべて設定できます。このガイドでは手動でのセットアップ方法を説明します。 **注意:** 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 設定をこれでラップしてください。このスニペットと以下のスニペットでは、緑の行が追加箇所、赤の行が削除箇所です。設定にすでにある options はそのまま残してください。 ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; // [!code ++] const nextConfig = {}; export default nextConfig; // [!code --] export default withGTConfig(nextConfig); // [!code ++] ``` このプラグインは翻訳設定を読み込み、裏側ですべてを自動的に連携します。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`](/docs/react/reference/functions/load-translations)** ファイルを作成します。これにより、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; } ``` **警告:** これらの翻訳ファイルは、作成するまで存在しません。そのため、最初の `npm run dev` ではコンパイルに失敗し、ページは HTTP 500 を返します。[`npx gt generate`](/docs/cli/reference/commands/generate) (API キー不要) または [`npx gt translate`](/docs/cli/reference/commands/translate) (認証情報あり) を実行するか、`public/_gt/[locale].json` に空の `{}` ファイルを追加してください。 `withGTConfig` は、`src/` ディレクトリまたはプロジェクトルートにある `loadTranslations.[js|ts]` ファイルを自動的に検出するため、追加の設定は不要です。 **注:** ローカル翻訳はアプリにバンドルされるため、外部サービスに依存せず即座に読み込まれます。詳しい内容とトレードオフについては、[翻訳の保存](/docs/react/guides/storing-translations) を参照してください。 ### 5. レイアウトに GTProvider を追加する **[`GTProvider`](/docs/react/reference/components/gt-provider)** コンポーネントを使うと、アプリ全体で翻訳を利用できるようになります。アプリを `root layout` レベルでラップする必要があります。既存のレイアウトの他の部分 (フォント、メタデータ、スタイル) はそのままにしておいてください。 ```tsx title="app/layout.tsx" import { GTProvider, useLocale } from 'gt-next'; // [!code ++] export default function RootLayout({ children }: { children: React.ReactNode }) { const locale = useLocale(); // [!code ++] return ( {/* [!code --] */} {/* [!code ++] */} {/* [!code --] */} {children} {/* [!code ++:3] */} {children} ); } ``` ### 6. 翻訳対象としてコンテンツをマークする次に、翻訳したいテキストを **[``](/docs/react/reference/components/t)** コンポーネントで囲みます。[``](/docs/react/reference/components/t) は "translate" の略です: ```tsx title="app/page.tsx" import { T } from 'gt-next'; // [!code ++] export default function Home() { return (

{/* [!code ++] */}

Welcome to my app

This content will be translated automatically.

{/* [!code ++] */}

); } ``` [``](/docs/react/reference/components/t) の中には、必要に応じて JSX を多くも少なくも含められます。中身は、テキスト、ネストした要素、書式設定も含めて、すべてひとまとまりで翻訳されます。 ### 7. 言語切り替え機能を追加するユーザーが言語を切り替えられるよう、**[``](/docs/react/reference/components/locale-selector)** を追加します: ```tsx title="app/page.tsx" import { T } from 'gt-next'; // [!code --] import { T, LocaleSelector } from 'gt-next'; // [!code ++] export default function Home() { return (

{/* [!code ++] */}

Welcome to my app

This content will be translated automatically.

); } ``` [`LocaleSelector`](/docs/react/reference/components/locale-selector) は、`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/en-US/signin) で取得するか、以下を実行してください: ```bash npx gt auth ``` **警告:** 開発環境では、`gtx-dev-` で始まるキーを使用してください。本番用キー (`gtx-api-`) は CI/CD 専用です。 `GT_API_KEY` をブラウザに公開したり、ソース管理にコミットしたりしないでください。はい。API キーがなくても、`gt-next` は標準的な i18n ライブラリとして動作します。開発時にオンデマンド翻訳は利用できませんが、次のことは引き続き可能です。 * 独自の翻訳ファイルを手動で用意する * すべてのコンポーネント ([``](/docs/react/reference/components/t)、[``](/docs/react/reference/components/var)、[`LocaleSelector`](/docs/react/reference/components/locale-selector) など) を使用する * [`npx gt generate`](/docs/cli/reference/commands/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`](/docs/react/reference/hooks/use-gt)** フックを使用します。これは、同期的なサーバーコンポーネントとクライアントコンポーネントの両方で動作します。 ```tsx title="app/contact/page.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return ( ); } ``` 非同期コンポーネントでは hooks は使えません。代わりに `gt-next/server` から [`getGT`](/docs/react/nextjs/reference/functions/get-gt) をインポートしてください。 ```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] ブラウザの cookie が有効になっていること、およびセレクターが [``](/docs/react/reference/components/gt-provider) の配下で render されていることを確認してください。ロケール routing が有効な場合は、ミドルウェア matcher と [`pathRegex`](/docs/react/nextjs/config#path-regex) に現在のルートが含まれていることも確認してください。これは想定どおりの動作です。開発環境では、翻訳はオンデマンドで行われます (コンテンツは API 経由でリアルタイムに翻訳されます) 。この遅延は **本番環境では発生しません**。すべての翻訳は [`npx gt translate`](/docs/cli/reference/commands/translate) によって事前生成されます。あいまいなテキストは、不正確な翻訳の原因になることがあります。たとえば、"apple" は果物を指す場合もあれば、会社を指す場合もあります。意味を明確にするために `$context` prop を追加してください。 ```jsx Apple ``` [``](/docs/react/reference/components/t)、[`useGT()`](/docs/react/reference/hooks/use-gt)、[`getGT()`](/docs/react/nextjs/reference/functions/get-gt) はいずれも `$context` に対応しています。 ## Next steps - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.