# General Translation React SDKs (gt-react, gt-next, gt-react-native): React SPA Quickstart
URL: https://generaltranslation.com/en-US/docs/react/react-spa-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Add multiple languages to a single-page React application.
By the end of this guide, your single-page React app will display content in multiple languages, with a language switcher your users can interact with.
In a single-page app, `gt-react` runs entirely in the browser — you initialize it once at startup with [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa), and you don't need a provider component.
**Prerequisites:**
- A client-side rendered React app (Vite, webpack, or similar)
- Node.js 18+
Your build system may require a newer Node.js version. For example, Vite 8 requires `^20.19.0 || >=22.12.0`.
**Tip:** Run `npx gt@latest` to configure the Vite bootstrap and translation loading with the [setup wizard](/docs/cli/quickstart). This guide covers manual setup.
**Note:** If your app renders on the server, follow the [React Quickstart](/docs/react/react-quickstart) instead.
## Choose your bundler [#bundlers]
The steps below use Vite as the primary example. For another build system, use
its setup guide for the entry point, bootstrap, and translation loader:
Configure the Vite HTML entry and translation loading.
Configure the webpack entry and translation context.
Configure esbuild entry points and output-target fallbacks.
Configure the Rollup input and a statically analyzable locale map.
Configure the Rolldown input and a statically analyzable locale map.
Declare the bootstrap, configuration, package, and translations as Bazel inputs.
After setup, follow [Internationalizing a React SPA](/docs/react/guides/spa/internationalizing-react-spa)
for SPA-specific guidance on JSX, strings, locale selection, and validation.
## Quickstart [#quickstart]
### 1. Install the packages
`gt-react` is the library that powers translations in your app. `gt` is the CLI tool that prepares your translations.
```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. Create a translation config file
Create a **`gt.config.json`** file in your project root. This tells the library which languages you support:
```json title="gt.config.json"
{
"defaultLocale": "en",
"locales": ["es", "fr", "ja"],
"files": {
"gt": {
"output": "src/_gt/[locale].json"
}
}
}
```
- **`defaultLocale`** — the language your app is written in (your source language).
- **`locales`** — the languages you want to translate into. Pick any from the [supported locales list](/docs/platform/dashboard/reference/supported-locales).
- **`files`** — tells the CLI where to save translation files. The `output` path should match the import path in your [`loadTranslations`](/docs/react/reference/functions/load-translations) function (Step 3).
The CLI scans JavaScript and TypeScript files under `src`, `app`, `pages`, and `components` by default. Set [`src`](/docs/cli/reference/config#src) when your source lives elsewhere.
**Note:** Bundlers like Vite import translation files as modules, so translation files should live inside `src/`.
### 3. Create a translation loader
In an SPA, `gt-react` needs a function to load translation files in the browser at runtime. Create a [`loadTranslations`](/docs/react/reference/functions/load-translations) file:
```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 {};
}
}
```
This function loads JSON translation files from your `src/_gt/` directory. The CLI generates these files when you run [`npx gt translate`](/docs/cli/reference/commands/translate).
**Rollup:** Plain Rollup cannot analyze the fully dynamic import above. Use the [static locale-loader map](/docs/react/guides/developing-spa-translations#setup) instead.
Create React App can use the source-directory loader above. If you prefer to keep generated translations in `public/`, change the CLI output to `public/_gt/[locale].json`:
```json title="gt.config.json"
{
"defaultLocale": "en",
"locales": ["es", "fr", "ja"],
"files": {
"gt": {
"output": "public/_gt/[locale].json"
}
}
}
```
Load the file over HTTP with `PUBLIC_URL`:
```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
try {
const response = await fetch(
`${process.env.PUBLIC_URL}/_gt/${locale}.json`
);
if (!response.ok) throw new Error('Translation file not found');
return await response.json();
} catch {
console.warn(`No translations found for ${locale}`);
return {};
}
}
```
### 4. Initialize the library
Call **[`initializeGTSPA`](/docs/react/reference/config#initialize-spa)** once at startup, before your app renders. It takes your config and translation loader, determines the user's locale, and loads the translations for it.
The most robust pattern is a small entry module that initializes GT first, then loads the rest of the app. This allows you to translate content at the module level.
```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';
await initializeGTSPA({
...gtConfig,
loadTranslations,
});
await import('./main'); // render the app only after GT is ready
```
CommonJS does not support top-level await. Wrap initialization in an async startup function and dynamically import the application afterward. This preserves the async boundary required for module-level [`t()`](/docs/react/reference/functions/t-function) calls.
```js title="src/index.js"
const { initializeGTSPA } = require('gt-react');
const gtConfig = require('../gt.config.json');
async function loadTranslations(locale) {
try {
return require(`./_gt/${locale}.json`);
} catch (error) {
console.warn(`No translations found for ${locale}`);
return {};
}
}
async function start() {
await initializeGTSPA({
...gtConfig,
loadTranslations,
});
await import('./main');
}
start().catch(console.error);
```
**Warning:** Do not require `main` before initialization. Requiring it evaluates module-level [`t()`](/docs/react/reference/functions/t-function) calls before translations are ready.
```tsx title="src/main.tsx"
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
createRoot(document.getElementById('root')!).render(
);
```
In Vite, update the module script tag in `index.html` to point at the new entry: change its `src` from `/src/main.tsx` to `/src/index.ts`.
```html title="index.html"
```
[`initializeGTSPA`](/docs/react/reference/config#initialize-spa) runs once at startup — the configuration is immutable for the lifetime of the app. After it resolves, translations can be resolved in any module. **You don't need to wrap your app in a provider.**
Create React App blocks imports from outside `src/` and does not enable top-level `await`. Keep the root `gt.config.json` for the CLI, rename your existing `src/index.tsx` entry to `src/main.tsx`, then create this new entry:
```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import loadTranslations from './loadTranslations';
async function start() {
await initializeGTSPA({
defaultLocale: 'en',
locales: ['es', 'fr', 'ja'],
loadTranslations,
});
await import('./main');
}
start().catch(console.error);
```
Keep these locale values synchronized with the root config whenever you add or remove a language. Leave `public/index.html` unchanged; Create React App already loads `src/index`.
**Tip:** Follow [Developing with SPA translations](/docs/react/guides/developing-spa-translations) to add the compiler and development credentials.
### 5. Mark content for translation
Now, wrap any text you want translated with the **[``](/docs/react/reference/components/t)** component. [``](/docs/react/reference/components/t) stands for "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.
);
}
```
You can wrap as much or as little JSX as you want inside [``](/docs/react/reference/components/t). Everything inside it — text, nested elements, even formatting — gets translated as a unit.
For strings outside React components, use **[`t()`](/docs/react/reference/functions/t-function)**. It works at module level because [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa) loads translations before the rest of your app:
```ts title="src/navigation.ts"
import { t } from 'gt-react';
export const navigation = [
{ label: t('Home'), href: '/' },
{ label: t('About'), href: '/about' },
];
```
### 6. Add a language switcher
Drop in a **[``](/docs/react/reference/components/locale-selector)** so users can change languages:
```tsx title="src/components/Welcome.tsx"
import { T, LocaleSelector } from 'gt-react';
export default function Welcome() {
return (