# gt-react: General Translation React SDK: React Quickstart
URL: https://generaltranslation.com/en-US/docs/react.mdx
---
title: React Quickstart
description: Easily internationalize your React app with gt-react
---

<Callout type='info'>
  **Quick Setup:** Try `npx gtx-cli@latest` for automatic configuration. See the
  [Setup Wizard](/docs/cli/init) guide or use our [AI tools
  integration](/docs/overview/ai-tools).
</Callout>

## Installation

Install the `gt-react` and `gtx-cli` packages:

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

  <Tab value="bun">
  ```bash
  bun add gt-react
  bun add --dev gtx-cli
  ```
  </Tab>
  <Tab value="pnpm">
  ```bash
  pnpm add gt-react
  pnpm add --save-dev gtx-cli
  ```
  </Tab>
</Tabs>

### `GTProvider`

The [`GTProvider`](docs/react/api/components/gtprovider) component provides translation context to client-side components. It manages locale state, translations, and enables the [`useGT`](docs/react/api/strings/use-gt) and [`useTranslations`](docs/react/api/dictionary/use-translations) hooks.

Add the [`GTProvider`](docs/react/api/components/gtprovider) to your root component:

```tsx title="src/App.tsx"
import { GTProvider } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations'; // local translations

export default function App() {
  return (
    <GTProvider
      config={gtConfig}
      loadTranslations={loadTranslations}
    >
      {/* Your app */}
    </GTProvider>
  );
}
```

And create a `loadTranslations` function to load translations from your public directory:
```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  try {
    const t = await import(`../public/_gt/${locale}.json`);
    return t.default;
  } catch (error) {
    console.warn(`Failed to load translations for locale ${locale}:`, error);
    return {};
  }
}
```

Create a [`gt.config.json`](/docs/cli/reference/config) file in your project root:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}
```

Customize the locales for your project. See [supported locales](/docs/overview/supported-locales) for options.

### Environment variables

Add to your `.env.local` file for development hot-reloading and on-demand translations:

```bash title=".env.local"
GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"
```

<Callout type="warn">
  **Dev vs prod keys:** Use a `gtx-dev-` key locally. Use a `gtx-api-` key in CI/CD if you run `gtx-cli translate` during deploy.
  Never expose `GT_API_KEY` to the browser or commit it to source control.
</Callout>

Get your free API keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or run:

```bash
npx gtx-cli auth
```

<Accordions>
  <Accordion title="Can I use my own translations?">
  `gt-react` is an i18n library that can work standalone without any environment variables.
  Without them, the library will act very similarly to other i18n libraries, and will still have core internationalization functionality.

However, `gt-react` also offers a native integration with the General Translation platform.
This integration unlocks additional functionality in the library, such as:

- Translation Hot Reloading in Development
- Automatic AI translations
- Syncing translations with the General Translation platform

To avoid using the General Translation platform, just don't set any environment variables.

  </Accordion>
</Accordions>

---

## Usage

Now you can start internationalizing your content. There are two main approaches:

### JSX content with `<T>`

Wrap JSX elements to translate them using the [`<T>`](docs/react/api/components/t) component:

```tsx
import { T } from 'gt-react';

function Welcome() {
  return (
    <T>
      <h1>Welcome to our app!</h1>
    </T>
  );
}
```

For dynamic content, use [variable components](docs/react/guides/variables) like [`<Var>`](docs/react/api/components/var):

```tsx
import { T, Var } from 'gt-react';

function Greeting({ user }) {
  return (
    <T>
      <p>
        Hello, <Var>{user.name}</Var>!
      </p>
    </T>
  );
}
```

See the guide on [using the `<T>` component](docs/react/guides/t) for more information.

### Plain strings with `useGT`

For attributes, labels, and plain text using the [`useGT`](docs/react/api/strings/use-gt) hook:

```tsx
import { useGT } from 'gt-react';

function ContactForm() {
  const gt = useGT();

  return (
    <input
      placeholder={gt('Enter your email')}
      aria-label={gt('Email input field')}
    />
  );
}
```

See the guide on [translating strings](docs/react/guides/strings) for more information.

---

## Testing your app

Test your translations by switching languages:

1. **Add a locale selection dropdown** using [`<LocaleSelector>`](docs/react/api/components/locale-selector):

   ```tsx
   import { LocaleSelector } from 'gt-react';

   function App() {
     return <LocaleSelector />;
   }
   ```

2. **Start your dev server**:

   <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
      <Tab value="npm">
      ```bash
      npm run dev
      ```
      </Tab>
      <Tab value="yarn">
      ```bash
      yarn run dev
      ```
      </Tab>
      <Tab value="bun">
      ```bash
      bun run dev
      ```
      </Tab>
      <Tab value="pnpm">
      ```bash
      pnpm run dev
      ```
      </Tab>
   </Tabs>

3. Visit your development app and change languages via the locale selection dropdown.

In development, translations happen on-demand (you'll see a brief loading time). In production, translations are pre-generated by the CLI.

### Troubleshooting

<Accordions>
  <Accordion title="My app's language is not changing, even though I've changed my browser's language.">
    **Browser Cookies**

    If you are deciding to test different languages by changing your browser's language, this issue may occur.

    Check your browser's cookies for your app.
    General Translation uses cookies to store the user's language preference.
    The cookie is called `generaltranslation.locale`, and all you need to do is delete it.
    Then, just double check you are using the desired preferred language and then
    refresh the page.

    How to check cookies:
    * [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)
    * [Edge](https://support.microsoft.com/en-us/microsoft-edge/delete-cookies-in-microsoft-edge-63947406-40ac-c3b8-57b9-2a946a29ae09)

  </Accordion>
  <Accordion title="Why do languages take a long time to load in dev?">
    **On-Demand Translation**

    You may notice when loading languages in development, translations will take a few seconds to be displayed.
    This happens because your app is being translated in real time.
    We refer to this process as an "on-demand translation".

    This **only happens in dev** so you can easily prototype your website in different languages.
    All translations are pre-generated in production, so there will be no delay.
    Follow our guide on [shipping to production](docs/react/tutorials/quickdeploy).

  </Accordion>
  <Accordion title="Why are some translations inaccurate?">
    The most likely cause of an inaccurate translation is ambiguous wording.
    For example, "apple" can be a fruit or a technology company.

    To fix this, you can provide more context to the translation with a `context` prop or option.
    The [`<T>`](docs/react/api/components/t) component supports the `context` prop, and the [`useGT`](docs/react/api/strings/use-gt) hook supports a `context` option.
    For example:
    ```jsx
    <T context="the technology company">Apple</T>
    ```
  </Accordion>
</Accordions>

---

## Deployment

For production, you need to pre-translate content since runtime translation is disabled.

1. **Get a production API key** from [dash.generaltranslation.com](https://dash.generaltranslation.com).

   Production keys begin with `gtx-api-` (different from dev keys which start with `gtx-dev-`). Learn more about [environment differences](docs/react/concepts/environments).

2. **Add to your CI/CD environment**:

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

   <Callout type='warn'>
     **Never** publicly expose your GT_API_KEY production key.
   </Callout>

3. **Run the translate command** to translate your content:

   ```bash
   npx gtx-cli translate
   ```

   You can configure the behavior of the translate command with the [`gt.config.json`](/docs/cli/reference/config) file.

   See the [CLI Tool](/docs/cli/translate) reference guide for more information.

4. **Update your build script** to translate before building:
   ```json title="package.json"
   {
     "scripts": {
       "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
     }
   }
   ```

<Accordions>
  <Accordion title="What if I'm not using the General Translation platform?">
    If you're not using the General Translation platform, you can still use `gt-react` in production.

    However, you'll need to manually translate your content before deploying your application.

    Instead of running `translate`, run the `generate` command to generate JSON files containing all of your translation data (in your source language).

    ```bash
    npx gtx-cli generate
    ```

    Then, you'll need to manually edit / translate these files, and load them into your application with [`loadTranslations`](docs/react/guides/local-tx).

  </Accordion>
</Accordions>

## Next steps

- [`<T>` Component Guide](docs/react/guides/t) - Deep dive into the [`<T>`](docs/react/api/components/t) component and JSX translation
- [String Translation Guide](docs/react/guides/strings) - Using [`useGT`](docs/react/api/strings/use-gt)
- [Variable Components](docs/react/guides/variables) - Handle dynamic content with [`<Var>`](docs/react/api/components/var), [`<Num>`](docs/react/api/components/num), etc.