# General Translation React SDKs (gt-react, gt-next): React SPA クイックスタート URL: https://generaltranslation.com/ja/docs/react/react-spa-quickstart.mdx --- title: React SPA クイックスタート description: General Translation を使って、10分以内にシングルページの React アプリに多言語対応を追加します。 related: links: - /docs/react/guides/developing-spa-translations - /docs/react/guides/translating-jsx - /docs/react/guides/managing-locales - /docs/react/guides/storing-translations --- # React SPA クイックスタート このガイドを終える頃には、シングルページの React アプリでコンテンツを複数の言語で表示できるようになり、ユーザーが操作できる言語切り替え機能も備わります。 シングルページアプリでは、`gt-react` は完全にブラウザ上で動作します。起動時に `initializeGTSPA()` で一度初期化するだけでよく、provider コンポーネントは必要ありません。 **前提条件:** * クライアントサイドでレンダリングされる React アプリ (Vite、webpack など) * Node.js 18+ **ヒント:** `npx gt@latest` を実行すると、[Setup Wizard](/docs/cli/reference/commands/init) を使って一通りの設定を行えます。このガイドでは手動でのセットアップを説明します。 **注:** アプリがサーバー側でレンダリングされる場合は、代わりに [React Quickstart](/docs/react/react-quickstart) を参照してください。 ## クイックスタート [#quickstart] ### 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/dashboard/reference/supported-locales) から任意に選んでください。 * **`files`** — CLI に翻訳ファイルの保存先を指定します。`output` パスは、`loadTranslations` 関数内の import パス (ステップ 3) と一致している必要があります。 **ファイルの場所:** Vite のようなバンドラは翻訳ファイルをモジュールとして import するため、`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` に変更してください。 ```html title="index.html" ``` `initializeGTSPA` は起動時に一度だけ実行され、この設定はアプリの実行中は変更できません。これが完了すると、どのモジュールからでも翻訳を取得できます。**アプリを provider でラップする必要はありません。** **ヒント:** compiler と開発用認証情報を追加するには、[SPA translations を使った開発](/docs/react/guides/developing-spa-translations) に従ってください。 ### 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 を必要な範囲だけ囲めます。中に含まれるものは、テキスト、ネストされた要素、フォーマットも含めて、すべて 1 つの単位として翻訳されます。 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` クッキーに保存し、ページを再読み込みします。その後 `initializeGTSPA` が再実行され、アプリがレンダリングされる前に新しいロケールの翻訳が読み込まれます。 ### 7. 認証して翻訳する 翻訳を始める前に、General Translation に認証してください。 ```bash npx gt auth ``` 画面の案内に従ってアカウントを作成するか、ログインします。キーの種類を尋ねられたら、本番用のキーを選択します。このコマンドにより APIキー と 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` で指定した出力パスに書き込みます。ソースコンテンツを変更したら、再度実行してください。 以上で完了です。これでアプリは多言語対応になりました。🎉 ## トラブルシューティング [#troubleshooting] `gt-react` は、ユーザーの言語設定を `generaltranslation.locale` という名前のクッキーに保存します。以前に別の言語でテストした場合、このクッキーが選択内容より優先されることがあります。クッキーを削除して、もう一度お試しください。 * [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` プロパティを追加してください。 ```jsx Apple ``` `` と `useGT()` はどちらも `$context` オプションに対応しています。 ## Next steps - /docs/react/guides/developing-spa-translations - /docs/react/guides/translating-jsx - /docs/react/guides/managing-locales - /docs/react/guides/storing-translations