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プラットフォームから本番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

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

詳細については、CLIツールリファレンスガイドを参照してください。

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

package.json

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

概要

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

次のステップ

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

Next.js クイックスタート

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

My app's language is not changing, even though I've changed my browser's language.

Why do languages take a long time to load in dev?

Why are some things translating and others not?

Why are some translations inaccurate?

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

このページについて