# gt-react: General Translation React SDK: SPA クイックスタート URL: https://generaltranslation.com/ja/docs/react/tutorials/quickstart-spa.mdx --- title: SPA クイックスタート description: 10分以内で、シングルページの React アプリに複数の言語を追加できます --- このガイドを終える頃には、シングルページの React アプリで複数の言語のコンテンツを表示し、ユーザーが操作できる言語切り替え機能も備えられるようになります。 シングルページアプリでは、`gt-react` は完全にブラウザ上で動作します。起動時に `initializeGTSPA()` で一度初期化するだけでよく、provider コンポーネントは必要ありません。 **前提条件:** * クライアントサイドでレンダリングされる React アプリ (Vite、webpack、または同様のもの) * Node.js 18+ **自動セットアップを使いたい場合** は、`npx gt@latest` を実行して [Setup Wizard](/docs/cli/init) ですべて設定できます。このガイドでは手動セットアップを説明します。 **サーバーレンダリングされるアプリですか？** アプリをサーバーでレンダリングしている場合は、代わりに [React クイックスタート](/docs/react) を参照してください。 *** ## ステップ1: パッケージをインストール `gt-react` は、アプリで翻訳を機能させるライブラリです。`gt` は、翻訳の準備を行う CLI ツールです。 ```bash npm i gt-react npm i -D gt ``` ```bash yarn add gt-react yarn add --dev gt ``` ```bash bun add gt-react bun add --dev gt ``` ```bash pnpm add gt-react pnpm add --save-dev gt ``` *** ## ステップ2: 翻訳設定ファイルを作成する プロジェクトのルートに **`gt.config.json`** ファイルを作成します。これにより、サポートする言語をライブラリに指定できます。 ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr", "ja"], "files": { "gt": { "output": "src/_gt/[locale].json" } } } ``` * **`defaultLocale`** — アプリの記述に使う言語 (ソース言語) です。 * **`locales`** — 翻訳先の言語です。[サポートされているロケールの一覧](/docs/platform/supported-locales) から自由に選べます。 * **`files`** — 翻訳ファイルの保存先を CLI に指定します。`output` のパスは、`loadTranslations` 関数内のインポートパス (ステップ 3) と一致させてください。 **ファイルの場所:** Vite のようなバンドラーは翻訳ファイルをモジュールとしてインポートするため、`src/` 内に配置してください。 *** ## ステップ 3: 翻訳ローダーを作成する SPA では、`gt-react` はランタイムでブラウザー内の翻訳ファイルを読み込むための関数を必要とします。`loadTranslations` ファイルを作成します: ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { try { const translations = await import(`./_gt/${locale}.json`); return translations.default; } catch (error) { console.warn(`No translations found for ${locale}`); return {}; } } ``` この関数は、`src/_gt/` ディレクトリにある JSON の翻訳ファイルを読み込みます。これらのファイルは、`npx gt translate` を実行すると CLI によって生成されます。 *** ## ステップ 4: ライブラリを初期化する アプリのレンダリング前、起動時に **`initializeGTSPA`** を一度呼び出します。これに設定と翻訳ローダーを渡すことで、ユーザーのロケールを判定し、そのロケールの翻訳を読み込みます。 最も堅牢なのは、まず GT を初期化し、その後でアプリの残りの部分を読み込む小さなエントリモジュールを使うパターンです: ```ts title="src/index.ts" import { initializeGTSPA } from 'gt-react'; import gtConfig from '../gt.config.json'; import loadTranslations from './loadTranslations'; await initializeGTSPA({ defaultLocale: gtConfig.defaultLocale, locales: gtConfig.locales, loadTranslations, }); await import('./main'); // GTの準備が完了した後にアプリをレンダリングする ``` ```tsx title="src/main.tsx" import { StrictMode } from 'react'; import { createRoot } from 'react-dom/client'; import App from './App'; createRoot(document.getElementById('root')!).render( ); ``` 次に、`index.html` の module script タグを更新して、新しいエントリを参照するようにします。`src` を `/src/main.tsx` から `/src/index.ts` に変更してください。 `initializeGTSPA` は起動時に一度だけ実行され、この設定はアプリの存続期間中ずっと変更できません。これが完了すると、アプリ内のすべてのコンポーネントとフックから翻訳にアクセスできます。**アプリを provider でラップする必要はありません。** **開発中にライブ翻訳を使いたいですか？** [SPA 開発時の翻訳ガイド](/docs/react/tutorials/spa-development-translations) に従って、compiler と開発用認証情報を追加してください。 *** ## ステップ 5: 翻訳するコンテンツをマークする 次に、翻訳したいテキストを **``** コンポーネントで囲みます。`` は "translate" の略です: ```tsx title="src/components/Welcome.tsx" import { T } from 'gt-react'; export default function Welcome() { return (

Welcome to my app

This content will be translated automatically.
); } ``` `` の中では、必要に応じて JSX を好きなだけ、あるいは最小限だけ囲めます。中にあるものは、テキスト、ネストされた要素、書式設定まで含めて、すべてひとまとまりで翻訳されます。 React コンポーネントの外にある文字列には、**`t()`** を使います。`initializeGTSPA()` はアプリの残りの部分より前に翻訳を読み込むため、モジュールレベルでも動作します。 ```ts title="src/navigation.ts" import { t } from 'gt-react'; export const navigation = [ { label: t('Home'), href: '/' }, { label: t('About'), href: '/about' }, ]; ``` *** ## ステップ 6: 言語切り替え機能を追加する ユーザーが言語を切り替えられるよう、**``** を追加します: ```tsx title="src/components/Welcome.tsx" import { T, LocaleSelector } from 'gt-react'; export default function Welcome() { return (

Welcome to my app

This content will be translated automatically.
); } ``` `LocaleSelector` は、`gt.config.json` の言語をもとにしたドロップダウンを表示します。 ユーザーが言語を選択すると、`gt-react` はその選択を `generaltranslation.locale` cookie に保存してページを再読み込みします。すると `initializeGTSPA` が再実行され、アプリがレンダリングされる前に新しいロケールの翻訳が読み込まれます。 *** ## ステップ7: 認証して翻訳する 翻訳を始める前に、General Translation で認証してください: ```bash npx gt auth ``` 画面の案内に従って、アカウントを作成するかログインしてください。キーの種類を尋ねられたら、本番用キーを選択します。このコマンドは API key と project ID を生成し、プロジェクトルートの `.env.local` に追加します。 ```bash title=".env.local" GT_PROJECT_ID="your-project-id" GT_API_KEY="gtx-api-your-production-key" ``` **キーは厳重に管理してください:** `.env.local` をコミットしたり、ブラウザーコード内で `GT_API_KEY` を公開したりしないでください。 続いて、設定されているすべてのロケール用の翻訳ファイルを生成するため、translate コマンドを実行します。 ```bash npx gt translate ``` CLI はアプリをスキャンし、その内容を翻訳して、結果を `gt.config.json` で指定した出力パスに書き込みます。source コンテンツが変更されたら、その都度もう一度実行してください。 以上です — これでアプリは多言語対応になりました。🎉 *** ## トラブルシューティング `gt-react` は、ユーザーの言語設定を `generaltranslation.locale` という cookie に保存します。以前に別の言語でテストしていた場合、この cookie が選択内容より優先されることがあります。クッキーを削除して、もう一度お試しください。 * [Chrome](https://support.google.com/chrome/answer/95647) * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored) * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0) テキストが曖昧だと、不正確な翻訳につながることがあります。たとえば、"apple" は果物を指す場合もあれば、会社を指す場合もあります。判別しやすくするために、`$context` prop を追加してください。 ```jsx Apple ``` `` と `useGT()` はどちらも `$context` オプションに対応しています。 *** ## 次のステップ * [**`` コンポーネントガイド**](/docs/react/guides/t) — 変数、複数形、高度な翻訳パターンについて学ぶ * [**文字列翻訳ガイド**](/docs/react/guides/strings) — `useGT` を詳しく学ぶ * [**変数コンポーネント**](/docs/react/guides/variables) — ``、``、``、`` を使って動的コンテンツを扱う * [**複数形処理**](/docs/react/api/components/plural) — `` コンポーネントで複数形を扱う * [**SPA 開発時の翻訳**](/docs/react/tutorials/spa-development-translations) — 開発中に翻訳がリアルタイムで更新されるのを確認する * [**本番環境へのデプロイ**](/docs/react/tutorials/quickdeploy) — CI/CD のセットアップ、キャッシュ、パフォーマンス最適化 * [**共有文字列**](/docs/react/guides/shared-strings) — `msg()` を使って、配列、設定オブジェクト、共有データ内のテキストを翻訳する