数分で React アプリのコンテンツ翻訳を開始できます。

前提条件: React、基本的な JavaScript の知識

インストール

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

npm i gt-react
npm i 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

設定

GTProvider

GTProvider コンポーネントは、React コンポーネントに翻訳用のコンテキストを提供します。locale の状態や翻訳を管理し、useGT および useTranslations フックを利用可能にします。

ルートの App コンポーネントに GTProvider を追加してください:

import { GTProvider } from 'gt-react';

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

プロジェクトのルートにgt.config.jsonファイルを作成します:

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

プロジェクトの対応ロケールをカスタマイズします。選択肢については、supported localesを参照してください。

環境変数

開発時のホットリロード用に、環境ファイルに追加してください:

VITE_GT_API_KEY="your-dev-api-key"
VITE_GT_PROJECT_ID="your-project-id"

REACT_APP_GT_API_KEY="your-dev-api-key"
REACT_APP_GT_PROJECT_ID="your-project-id"

GATSBY_GT_API_KEY="your-dev-api-key"
GATSBY_GT_PROJECT_ID="your-project-id"

REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
REDWOOD_ENV_GT_PROJECT_ID="your-project-id"

無料の API Keys は dash.generaltranslation.com で取得するか、次を実行してください:

npx gtx-cli auth

使い方

ここからコンテンツの国際化を始められます。主なアプローチは2つあります。

JSX コンテンツと <T>

<T> コンポーネントで翻訳できるよう、JSX 要素をラップします:

import { T } from 'gt-react';

function Welcome() {
  return (
    <T>
      <h1>私たちのアプリへようこそ！</h1>
    </T>
  );
}

動的コンテンツには、変数コンポーネント（例: <Var>）を使用します。

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

function Greeting({ user }) {
  return (
    <T>
      <p>こんにちは、<Var>{user.name}</Var>さん！</p>
    </T>
  );
}

詳しくは、<T> コンポーネントの使い方ガイドをご覧ください。

useGT を使ったプレーンな文字列

属性やラベル、プレーンテキストには、useGT フックを使用します:

import { useGT } from 'gt-react';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('メールアドレスを入力')}
      aria-label={t('メール入力欄')}
    />
  );
}

詳しくは、文字列の翻訳 ガイドをご覧ください。

アプリのテスト

言語を切り替えて翻訳をテストします:

1. <LocaleSelector> を使ってロケール選択用のドロップダウンを追加します:

   import { LocaleSelector } from 'gt-react';
   
   function App() {
     return <LocaleSelector />;
   }

2. 開発サーバーを起動します:

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. localhost:3000 にアクセスし、ロケール選択ドロップダウンから言語を切り替えます。

開発環境では翻訳はオンデマンドで行われ（短い読み込みが発生します）、本番環境ではすべて事前に翻訳されています。

トラブルシューティング

デプロイ

本番環境ではランタイム翻訳が無効（<Tx> と tx 関数を除く）のため、コンテンツは事前に翻訳しておく必要があります。

1. dash.generaltranslation.com から本番用の APIキーを取得します。

   本番用キーは gtx-api- で始まります（開発用キーは gtx-dev- で始まります）。環境の違いについて詳しくはご確認ください。

2. CI/CD 環境に追加します:

   GT_PROJECT_ID=your-project-id
   GT_API_KEY=gtx-api-your-production-key

   本番用キーにフレームワークの公開変数プレフィックス（VITE_、REACT_APP_ など）を絶対に付けないでください。サーバーサイド専用のままにする必要があります。

3. コンテンツを翻訳するためにtranslate コマンドを実行します:

   npx gtx-cli translate

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

   詳細は CLI ツール のリファレンスガイドをご覧ください。

4. ビルド前に翻訳が走るよう、ビルドスクリプトを更新します:

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

次のステップ

• <T> コンポーネントガイド - <T> コンポーネントと JSX 翻訳の詳細解説
• 文字列翻訳ガイド - 文字列翻訳に useGT を使う
• Variable コンポーネント - <Var>、<Num> などで動的コンテンツを扱う