# General Translation React SDKs (gt-react, gt-next, gt-react-native): React Quickstart
URL: https://generaltranslation.com/en-US/docs/react/react-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Add multiple languages to a server-rendered React app with General Translation in under 10 minutes.

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+

<Callout type='info'>
  **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.
</Callout>


## 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.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
  ```bash
  npm i gt-react
  npm i -D gt
  ```
  </Tab>
  <Tab value="yarn">
  ```bash
  yarn add gt-react
  yarn add --dev gt
  ```
  </Tab>
  <Tab value="bun">
  ```bash
  bun add gt-react
  bun add --dev gt
  ```
  </Tab>
  <Tab value="pnpm">
  ```bash
  pnpm add gt-react
  pnpm add --save-dev gt
  ```
  </Tab>
</Tabs>


### 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).


### 3. Create a translation loader

Create a [`loadTranslations`](/docs/react/reference/functions/load-translations) 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`](/docs/cli/reference/commands/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`](/docs/react/reference/config#initialize)** 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`](/docs/react/reference/functions/get-translations-snapshot)**, then pass both to **[`<GTProvider>`](/docs/react/reference/components/gt-provider)**:

```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 (
    <GTProvider locale={locale} translations={translations}>
      {children}
    </GTProvider>
  );
}
```


### 6. Mark content for translation

Wrap any text you want translated with the **[`<T>`](/docs/react/reference/components/t)** component. [`<T>`](/docs/react/reference/components/t) stands for "translate":

```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

For plain strings — like `placeholder` attributes or `aria-label` values — use the **[`useGT`](/docs/react/reference/hooks/use-gt)** hook:

```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';

export default function ContactForm() {
  const gt = useGT();
  return <input placeholder={gt('Enter your email')} />;
}
```


### 7. Add a language switcher

Drop in a **[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)** so users can change languages:

```tsx title="src/components/Header.tsx"
import { LocaleSelector } from 'gt-react';

export default function Header() {
  return <LocaleSelector />;
}
```

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`](/docs/react/reference/config#initialize).

Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) or by running:

```bash
npx gt auth
```

<Callout type="warn">
  **Warning:** For development, use a key starting with `gtx-dev-`. Production keys (`gtx-api-`) are for CI/CD only.
</Callout>


### 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 && <YOUR_BUILD_COMMAND>"
  }
}
```

Set your **production** environment variables in your hosting provider:

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  **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`.
</Callout>

That's it — your app is now multilingual. 🎉


## Troubleshooting [#troubleshooting]

<Accordions>
  <Accordion title="The language isn't changing when I use the dropdown">
    Confirm that browser cookies are enabled, the selected locale appears in `gt.config.json`, and the selector renders under [`<GTProvider>`](/docs/react/reference/components/gt-provider). If you provide a custom [`_reload`](/docs/react/reference/components/gt-provider#reload) callback, verify that it reloads or navigates after selection.
  </Accordion>
  <Accordion title="Translations are slow in development">
    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`](/docs/cli/reference/commands/translate).
  </Accordion>
  <Accordion title="Some translations are inaccurate">
    Ambiguous text can lead to inaccurate translations. For example, "apple" could mean the fruit or the company. Add a `$context` prop to help:

    ```jsx
    <T $context="the technology company">Apple</T>
    ```

    Both [`<T>`](/docs/react/reference/components/t) and [`useGT()`](/docs/react/reference/hooks/use-gt) support the `$context` option.
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.