数分で 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つのアプローチがあります。

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

<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 Tool のリファレンスガイドをご覧ください。

4. ビルドスクリプトを更新し、ビルド前に翻訳を実行します:

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

次のステップ

• <T> コンポーネントガイド - <T> コンポーネントと JSX 翻訳を深掘り
• 文字列翻訳ガイド - 文字列翻訳に useGT を使う
• 変数コンポーネント - <Var>、<Num> などで動的コンテンツを扱う