クイックスタート

概要

このクイックスタートガイドでは、gt-reactを使用してReactアプリを国際化する方法を説明します。

このガイドを完了すると、完全に国際化されたReactアプリが完成します。

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

インストール

設定

使用方法

アプリのテスト

デプロイ

前提条件

サポートされているフレームワーク（Next.js、Viteなど）を使用したReactプロジェクト
ReactとJavaScriptの基本的な知識

インストール

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

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

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

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

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

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

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

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

設定

`GTProvider`

gt-reactの中核はGTProviderコンポーネントです。

これは以下の責任を持ちます：

ユーザーの現在のロケールを管理する
アプリケーションに関連する翻訳を提供する
翻訳にアクセスするためのフックにコンテキストを提供する
ユーザーのロケールを変更するためのフックにコンテキストを提供する

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

src/App.tsx

import { GTProvider } from 'gt-react';

export default function App() {
  return (
    <GTProvider>
      <App />
    </GTProvider>
  );
}

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

gt.config.json

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

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

最後に、gt.config.jsonファイルをプロバイダーのpropsにスプレッドします。

import gtConfig from './gt.config.json';

<GTProvider {...gtConfig}>
  <App />
</GTProvider>

gt.config.jsonファイルをスプレッドすることで、アプリケーションとCLIツール全体で設定の一貫性が保たれます。

または、GTProviderコンポーネントで各propを個別に指定することもできます。

<GTProvider
  defaultLocale="en"
  locales={["fr", "es"]}
>

環境変数

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

VITE_GT_API_KEY="" # Your General Translation Developer API key
VITE_GT_PROJECT_ID="" # Your General Translation project ID

GATSBY_GT_API_KEY="" # Your General Translation Developer API key
GATSBY_GT_PROJECT_ID="" # Your General Translation project ID

REDWOOD_ENV_GT_API_KEY="" # Your General Translation Developer API key
REDWOOD_ENV_PROJECT_ID="" # Your General Translation project ID

NEXT_PUBLIC_GT_API_KEY="" # Your General Translation Developer API key
NEXT_PUBLIC_GT_PROJECT_ID="" # Your General Translation project ID

REACT_APP_GT_API_KEY="" # Your General Translation Developer API key
REACT_APP_GT_PROJECT_ID="" # Your General Translation project ID

多くのReactフレームワークは、環境変数をクライアントにエクスポートする独自の方法を持っています。開発環境では、GT_API_KEYとGT_PROJECT_IDの両方をクライアントにエクスポートする必要があります。

これまでにいくつかのライブラリのサポートを追加しましたが、お使いのフレームワークがリストにない場合は、GitHubリポジトリでissueを作成してお知らせください。

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

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

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

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

使用方法

素晴らしい！上記の手順に従った場合、あなたのReactプロジェクトはgt-reactを使用する準備が整いました。

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

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

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

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

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

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

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

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

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

`useGT` フック

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

import { useGT } from 'gt-react';

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

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

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

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

アプリのテスト

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

異なる言語でアプリを確認する

<LocaleSelector>コンポーネントをアプリに追加します。これにより、アプリの言語を選択できるようになります。

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

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

npm run dev

yarn run dev

bun run dev

pnpm run dev

お好みのブラウザでアプリを開きます（通常は http://localhost:3000）。

トラブルシューティング

デプロイメント

素晴らしい！翻訳とアプリの機能に満足している場合、アプリケーションをデプロイできます。

本番環境でのgt-reactの動作は、開発環境とは少し異なります。具体的には、実行時に翻訳は実行されません。

これは、アプリケーションをデプロイする前に、ビルドプロセスでコンテンツを翻訳する必要があることを意味します。

幸い、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_やVITE_のプレフィックスが付いていないことを確認してください！

付いている場合、APIキーが公開される危険性があります。

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

npx gtx-cli translate

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

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

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

package.json

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

サマリー

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

次のステップ

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

クイックスタート

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

ブラウザの言語を変更したのに、アプリの言語が変わりません。

新しい言語の読み込みに時間がかかるのはなぜですか？

一部は翻訳されているのに、他の部分が翻訳されないのはなぜですか？

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

General Translation platformを使用していない場合はどうすればよいですか？

このページについて