数分で 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"]
}

プロジェクトの対応ロケールをカスタマイズします。options については 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"

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

npx gtx-cli auth

使い方

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

<T> を使った JSX コンテンツ

<T> コンポーネントで JSX 要素をラップして翻訳します：

import { T } from 'gt-react';

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

動的コンテンツには、<Var> のような variable components を使用します。

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. 本番用のAPIキーを取得してください: dash.generaltranslation.com。

   本番キーは 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> などで動的コンテンツを扱う