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

無料の 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> のような 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. 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

   本番用キーに、フレームワークの公開用 Variable のプレフィックス（VITE_ や REACT_APP_ など）を絶対に付けないでください。サーバーサイドのみに留めてください。

3. 翻訳コマンドを実行してコンテンツを翻訳します:

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