Next.js クイックスタート

概要

このクイックスタートガイドでは、gt-next を使って Next.js アプリケーションをセットアップする方法を説明します。

このガイドを終えると、コンテンツの翻訳を始める準備が整った Next.js アプリが完成します。

本ガイドでは、以下の内容を扱います。

インストール

設定

使い方

アプリのテスト

デプロイ

前提条件

App Router を使用している Next.js アプリケーション
Next.js および JavaScript の基本的な知識

インストール

gt-nextとgtx-cliパッケージをインストールします：

npm i gt-next
npm i --save-dev gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

自動セットアップ： gt-nextを使用してプロジェクトをセットアップするのに役立つ実験的なセットアップウィザードがあります。

npx gtx-cli@latestを実行して試してみてください。文字列の国際化は手動で行う必要がありますが、開始するのに役立ちます。

詳細については、セットアップウィザードリファレンスガイドをご覧ください。

または、Claude Code、Cursor、Windsurfなどのツールにプロジェクトを自動的にセットアップしてもらいたい場合は、 mcpサーバーを使用できます。

設定

`withGTConfig`

withGTConfig関数は、Next.jsアプリケーションでSDKを初期化するために使用される関数です。

これをnext.config.[js|ts]ファイルに配置してください。

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // Your next.config.ts options
};

export default withGTConfig(nextConfig, {
  // Additional GT configuration options
});

詳細については、withGTConfig APIリファレンスを参照してください。

`GTProvider`

gt-nextはGTProviderコンポーネントもエクスポートします。このコンポーネントは、Next.jsアプリケーションのクライアントサイドコンポーネントにコンテキストを提供するために使用されます。

GTProviderとwithGTConfigは連携して、アプリケーションにコンテキストを提供します。

このコンテキストには以下が含まれます：

ユーザーの現在のロケールの管理
そのロケールに関連する翻訳
useGTフックのコンテキスト
useTranslationsフックのコンテキスト

まず、アプリケーションのルートレイアウトにGTProviderコンポーネントを追加します。コンポーネントツリーの可能な限り上位に配置する必要があります。

src/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

複数のルートレイアウトがある場合は、それぞれにGTProviderを配置してください。

次に、プロジェクトのルートにgt.config.jsonファイルを作成します。このファイルは、gtx-cliツールとgt-nextライブラリの両方を設定するために使用されます。

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}

プロジェクトに合わせてdefaultLocaleとlocalesをカスタマイズしてください。詳細については、サポートされているロケールのリストを参照してください。

withGTConfigは、プロジェクト内のgt.config.jsonファイルを自動的に検出し、それを使用してSDKを設定します。

環境変数

以下の環境変数を設定してください：

GT_API_KEY="" # Your General Translation Developer API key
GT_PROJECT_ID="" # Your General Translation project ID

APIキー変数は開発環境でのみ設定されていることを確認してください！本番環境では設定しないでください。

General Translationアカウントを作成することで、無料のAPIキーとプロジェクトIDを取得できます。

アカウント作成後、Development API Keysページに移動して、Dev APIキーとプロジェクトIDを取得してください。

または、CLIツールコマンドnpx gtx-cli authを使用して、プロジェクト用のAPIキーとプロジェクトIDを生成し、.env.localファイルに保存することもできます。

使用方法

素晴らしい！上記の手順に従った場合、Next.jsアプリはgt-nextを使用するように設定されています。

次のステップは、コンテンツを国際化することです。ここでは、アプリケーション内でコンテンツを翻訳するさまざまな方法について簡単に概要を説明します。

`<T>` コンポーネント

<T>コンポーネントは、アプリケーション内でJSXコンテンツを翻訳するためのメインコンポーネントです。

使用するには、翻訳したいJSXを<T>コンポーネントで囲むだけです。

import { T } from 'gt-next';
<T>
  <div>Your content</div>
</T>

動的コンテンツがある場合は、変数コンポーネントを使用して動的な値を渡す必要があります。

import { T, Var } from 'gt-next';

<T>
  <div>Hello, <Var>{name}</Var>!</div>
</T>

詳細については、JSXの翻訳ガイドを参照してください。

`useGT` フック

useGTフックは、文字列を翻訳するために使用できる関数を返すReactフックです。

import { useGT } from 'gt-next'

const translate = useGT();
translate('Hello, world!');

useGTフックは、クライアントサイドとサーバーサイドの両方のコンポーネントで使用できます。非同期コンポーネントの場合は、代わりに非同期のgetGT()関数を使用してください。

詳細については、文字列の翻訳ガイドを参照してください。

ホットリロード翻訳機能を活用することで、アプリケーションの国際化に役立ちます。

これを有効にするには、開発環境でGT_API_KEYとGT_PROJECT_ID環境変数が設定されていることを確認してください。

アプリのテスト

おめでとうございます！ 🥳 上記の手順に従った場合、あなたのアプリはマルチリンガルになりました！実際に動作を確認してみましょう。

アプリを別の言語で表示する

アプリに <LocaleSelector> コンポーネントを追加してください。これにより、アプリの言語を切り替えることができます。

ヒント： このステップをスキップして、ブラウザの設定で言語を変更することもできます。

Next.js アプリを開発モードで起動します。

npm run dev

yarn run dev

bun run dev

pnpm run dev

お好みのブラウザでアプリを開いてください（通常は http://localhost:3000 です）。

トラブルシューティング

デプロイ

素晴らしいです！翻訳やアプリの動作に満足したら、アプリケーションをデプロイできます。

本番環境での gt-next の挙動は、開発環境とは少し異なります。特に、（<Tx> コンポーネントと tx 関数を除き）本番環境では実行時に翻訳は行われません。

つまり、アプリケーションをデプロイする前に、ビルドプロセスでコンテンツを翻訳しておく必要があります。

幸いなことに、gtx-cli ツールにはコンテンツを自動的に翻訳できる translate コマンドがあります。

まず、General Translation platform から本番用APIキーを取得する必要があります。

このキーは開発用APIキーとは異なり、gtx-dev- ではなく gtx-api- で始まることにご注意ください。

開発用キーと本番用キーの違いについてはこちらをご覧ください。

この環境変数をCI/CDパイプラインに追加してください。

GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>

GT_API_KEY が 絶対に NEXT_PUBLIC_ で始まらないようにしてください！

もしそうなっている場合、APIキーが公開されるリスクがあります。

translate コマンドを実行して、コンテンツを翻訳します。

npx gtx-cli translate

gt.config.json ファイルで translate コマンドの挙動を設定できます。

詳しくは CLI Tool リファレンスガイドをご覧ください。

ビルドプロセスに translate コマンドを追加します。

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

サマリー

このガイドでは、Next.jsアプリをgt-nextでセットアップする方法について説明しました。
アプリケーション内のコンテンツを翻訳するさまざまな方法について簡単に紹介しました。
コンテンツの国際化が完了した後、アプリケーションをデプロイする方法についても説明しました。

次のステップ

<T> コンポーネントを使ってJSXコンテンツを翻訳する方法について学ぶ: JSXの翻訳
useGT フックを使って文字列を翻訳する方法について学ぶ: 文字列の翻訳
ローカル翻訳の使い方を学ぶ: ローカル翻訳

Next.js クイックスタート

General Translationプラットフォームを使用したくない場合はどうすればよいですか？

アプリの言語が変わらない（ブラウザの言語を変更しても）

なぜ開発環境では言語の読み込みに時間がかかるのですか？

なぜ一部だけ翻訳されて、他は翻訳されないのですか？

なぜ一部の翻訳が正確でないのですか？

General Translation platform を使っていない場合は？

このページについて