# General Translation React SDKs (gt-react, gt-next): React Quickstart
URL: https://generaltranslation.com/en-US/docs/react/react-quickstart.mdx
---
title: React Quickstart
description: Add multiple languages to a server-rendered React app with General Translation in under 10 minutes.
related:
links:
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables
---
# React Quickstart
By the end of this guide, your server-rendered React app will display content in multiple languages, with a language switcher your users can interact with.
**Prerequisites:**
- A server-rendered React app (React Router or a custom SSR setup)
- Node.js 18+
**Note:** If your app renders entirely in the browser with Vite, follow the [React SPA Quickstart](/docs/react/react-spa-quickstart) instead. It skips the provider entirely.
## Quickstart [#quickstart]
### 1. Install the packages
`gt-react` is the library that powers translations in your app. `gt` is the CLI tool that prepares translations for production.
```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` function (Step 3).
### 3. Create a translation loader
Create a `loadTranslations` function that loads a locale's translation file. On the server this runs during rendering; the CLI generates the files when you run `npx gt translate`:
```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) {
return {};
}
}
```
### 4. Initialize the library
Call **`initializeGT`** at module scope in a file that loads on both the server and the client — your root route or layout is the natural place. It registers your config and translation loader once; the configuration is immutable for the lifetime of the app:
```tsx title="src/routes/root.tsx"
import { initializeGT } from 'gt-react';
import gtConfig from '../../gt.config.json';
import loadTranslations from '../loadTranslations';
initializeGT({
defaultLocale: gtConfig.defaultLocale,
locales: gtConfig.locales,
loadTranslations,
});
```
### 5. Load translations on the server
In your root route's loader (or equivalent server handler), resolve the request locale and fetch a translations snapshot with **`getTranslationsSnapshot`**, then pass both to **``**:
```tsx title="src/routes/root.tsx"
import {
GTProvider,
getTranslationsSnapshot,
parseLocale,
} from 'gt-react';
// In your route loader (exact API depends on your framework)
export async function loader({ request }) {
const locale = parseLocale(request); // [!code highlight]
return {
locale,
translations: await getTranslationsSnapshot(locale), // [!code highlight]
};
}
export default function Root({ children }) {
const { locale, translations } = useLoaderData();
return (
{children}
);
}
```
### 6. Mark content for translation
Wrap any text you want translated with the **``** component. `` 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.
);
}
```
For plain strings — like `placeholder` attributes or `aria-label` values — use the **`useGT`** hook:
```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';
export default function ContactForm() {
const gt = useGT();
return ;
}
```
### 7. Add a language switcher
Drop in a **``** so users can change languages:
```tsx title="src/components/Header.tsx"
import { LocaleSelector } from 'gt-react';
export default function Header() {
return ;
}
```
When the user picks a language, `gt-react` persists the choice in the `generaltranslation.locale` cookie and reloads the page, so the server re-renders everything in the new locale.
### 8. Set up environment variables (optional)
On-demand development translations run in the browser. Expose your Project ID and development API key to client code using your framework's public environment variables. Never expose a production API key.
With Vite, `gt-react` reads these variables automatically:
```bash title=".env.local"
VITE_GT_PROJECT_ID="your-project-id"
VITE_GT_DEV_API_KEY="your-dev-api-key"
```
For other frameworks, use their client environment-variable convention and pass the exposed values to `initializeGT`.
Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or by running:
```bash
npx gt auth
```
**Warning:** For development, use a key starting with `gtx-dev-`. Production keys (`gtx-api-`) are for CI/CD only.
### 9. Deploy to production
In production, translations are pre-generated at build time (no real-time API calls). Add the translate command to your build script:
```json title="package.json"
{
"scripts": {
"build": "npx gt translate && "
}
}
```
Set your **production** environment variables in your hosting provider:
```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
**Warning:** Production keys start with `gtx-api-` (not `gtx-dev-`). Get one from [dash.generaltranslation.com](https://dash.generaltranslation.com). Never publicly expose your `GT_API_KEY`.
That's it — your app is now multilingual. 🎉
## Troubleshooting [#troubleshooting]
`gt-react` stores the user's language preference in a cookie called `generaltranslation.locale`. If you previously tested with a different language, this cookie may override your selection. Clear your cookies and try again.
- [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)
This is expected. In development, translations happen on-demand (your content is translated in real time via the API). This delay **does not exist in production** — all translations are pre-generated by `npx gt translate`.
Ambiguous text can lead to inaccurate translations. For example, "apple" could mean the fruit or the company. Add a `$context` prop to help:
```jsx
Apple
```
Both `` and `useGT()` support the `$context` option.
## Next steps
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables