# gt-next: General Translation Next.js SDK: Next.js クイックスタート URL: https://generaltranslation.com/ja/docs/next.mdx --- title: Next.js クイックスタート description: 10分以内でNext.jsアプリに多言語対応を追加 --- このガイドを終える頃には、Next.jsアプリで複数言語のコンテンツを表示でき、ユーザーが操作できる言語切り替えも利用できるようになります。 **前提条件：** * **App Router** を使用するNext.jsアプリ (Next.js 13+) * Node.js 18+ **自動セットアップを使いたい場合**：`npx gt@latest` を実行すると、[セットアップウィザード](/docs/cli/init)を使ってすべて設定できます。このガイドでは手動セットアップを説明します。 *** ## ステップ 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/supported-locales)から任意に選択します。 * **`files.gt.output`** — CLI が翻訳ファイルを保存する場所です。`[locale]` は各言語コード (例: `public/_gt/es.json`) に置き換えられます。 **`.gitignore`** に `public/_gt/` を追加してください。これらのファイルは手動で作成するものではなく、自動生成されます。 ```txt title=".gitignore" public/_gt/ ``` *** ## ステップ4: レイアウトにGTProviderを追加する **`GTProvider`** コンポーネントを使うと、アプリ全体で翻訳を利用できるようになります。ルートレイアウトレベルでアプリをラップする必要があります。 ```tsx title="app/layout.tsx" import { GTProvider } from 'gt-next'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` `GTProvider` は**サーバーコンポーネント**です。サーバーで翻訳を読み込み、クライアントコンポーネントに渡します。 *** ## ステップ 5: コンテンツを翻訳対象としてマークする次に、翻訳したいテキストを **``** コンポーネントで囲みます。`` は "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 を広く囲むことも、最小限だけ囲むこともできます。中に含まれるものは、テキスト、ネストされた要素、書式までも含めて、ひとまとまりとして翻訳されます。 *** ## ステップ6: 言語切り替えを追加するユーザーが言語を切り替えられるよう、**``** を追加します: ```tsx title="app/page.tsx" import { T, LocaleSelector } from 'gt-next'; export default function Home() { return (

私のアプリへようこそ

このコンテンツは自動的に翻訳されます。

); } ``` `LocaleSelector` は、`gt.config.json` に含まれる言語を表示するドロップダウンをレンダリングします。 *** ## ステップ 7: 環境変数を設定する (任意) 開発中に翻訳を確認するには、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` を実行して翻訳ファイルのテンプレートを作成し、自分で翻訳する *** ## ステップ 8: 動作を確認する開発サーバーを起動します。 ```bash npm run dev ``` ```bash yarn dev ``` ```bash bun dev ``` ```bash pnpm dev ``` [http://localhost:3000](http://localhost:3000) を開き、言語ドロップダウンで言語を切り替えます。コンテンツが翻訳されて表示されることを確認してください。開発環境では、翻訳はオンデマンドで行われます。そのため、新しい言語に初めて切り替えるときは、短時間読み込み状態が表示されることがあります。本番環境では、翻訳は事前に生成されるため、すぐに読み込まれます。 *** ## ステップ9: JSX だけでなく文字列も翻訳する `placeholder` 属性、`aria-label` の値、`alt` テキストのようなプレーンな文字列には、**`useGT`** フックを使います。これはサーバーコンポーネントとクライアントコンポーネントの両方で使えます。 ```tsx title="app/contact/page.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return ( ); } ``` サーバーコンポーネントで `async/await` を使いたい場合は、`gt-next/server` から `getGT` をインポートします。 ```tsx import { getGT } from 'gt-next/server'; export default async function Page() { const gt = await getGT(); return

{gt('Hello')}

; } ``` *** ## ステップ10: 本番環境にデプロイする本番環境では、翻訳はビルド時に事前生成されるため、リアルタイムの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_` を先頭に付けないでください。これで完了です。アプリは多言語対応になりました。🎉 *** ## トラブルシューティング `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` によって事前生成されます。テキストが曖昧だと、不正確な翻訳につながることがあります。たとえば、"apple" は果物を指す場合もあれば、会社を指す場合もあります。補足情報として `context` prop を追加してください。 ```jsx Apple ``` ``、`useGT()`、`getGT()` はいずれも `context` オプションに対応しています。 *** ## 次のステップ **実際の動作を見る:** [実際に動作するサンプルアプリ](/docs/next/tutorials/examples) を参照して実プロジェクトでの `gt-next` のパターンを確認するか、直接 [アプリカタログ](https://app-catalog.generaltranslation.dev) にアクセスしてください。 * [**`` コンポーネントガイド**](/docs/next/guides/t) — 変数、複数形、高度な翻訳パターンについて学習する * [**文字列翻訳ガイド**](/docs/next/guides/strings) — `useGT` と `getGT` を詳しく解説 * [**変数コンポーネント**](/docs/next/guides/variables) — ``、``、``、`` を使って動的なコンテンツを扱う * [**複数形処理**](/docs/next/api/components/plural) — `` コンポーネントで複数形を扱う * [**ページメタデータの翻訳**](/docs/next/api/strings/get-gt#metadata) — `getGT` を使ってタイトル、説明、OG タグを翻訳する * [**本番環境へのデプロイ**](/docs/next/tutorials/quickdeploy) — CI/CD のセットアップ、キャッシュ、パフォーマンスの最適化 * [**共有文字列**](/docs/next/guides/shared-strings) — `msg()` を使って配列、設定オブジェクト、共有データ内のテキストを翻訳する