# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configuring General Translation
URL: https://generaltranslation.com/en-US/docs/react/guides/configuring.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How to initialize General Translation, configure credentials, and deliver translations with `<GTProvider>`.

Server-rendered React and each framework integration need configuration plus a [`GTProvider`](/docs/react/reference/components/gt-provider) that exposes translations to your components. React SPAs initialize directly with [`initializeGTSPA`](/docs/react/reference/config#initialize-spa); follow the [React SPA Quickstart](/docs/react/react-spa-quickstart) for that setup.

*Note: `gt-react`, `gt-tanstack-start`, and `gt-react-native` do not read `gt.config.json` automatically — import it and pass its fields into the initialization call. In Next.js, the [`withGTConfig`](/docs/react/nextjs/config) plugin reads `gt.config.json` for you.*

## Initialize the library [#initialize]

Configure General Translation once, before your first render.

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    Call [`initializeGT`](/docs/react/reference/config#initialize) once in a module that loads on both the server and client. Your framework resolves the request locale and provides the matching translations during server rendering.

    ```tsx title="src/routes/root.tsx"
    import { initializeGT } from 'gt-react';
    import gtConfig from '../../gt.config.json';

    const loadTranslations = (locale: string) =>
      import(`../_gt/${locale}.json`).then((m) => m.default);

    initializeGT({ ...gtConfig, loadTranslations });
    ```

    The [`loadTranslations`](/docs/react/reference/functions/load-translations) and [`loadDictionary`](/docs/react/reference/functions/load-dictionary) callbacks, credentials, and locale configuration all go on the initialization call — not on [`GTProvider`](/docs/react/reference/components/gt-provider).
  </Tab>

  <Tab value="Next.js">
    Next.js has no manual initialization call. Add the [`withGTConfig`](/docs/react/nextjs/config) plugin to `next.config.ts`; it reads `gt.config.json` and wires up translation at build and request time.

    ```ts title="next.config.ts"
    import { withGTConfig } from 'gt-next/config';

    const nextConfig = {};

    export default withGTConfig(nextConfig, {
      // options such as `dictionary`, `loadTranslationsPath`, and locale overrides
    });
    ```
  </Tab>

  <Tab value="TanStack Start">
    Call [`initializeGT`](/docs/react/reference/config#initialize) once during server and client startup, spreading in your config.

    ```tsx
    import { initializeGT } from 'gt-tanstack-start';
    import gtConfig from '../gt.config.json';

    const loadTranslations = (locale: string) =>
      import(`./_gt/${locale}.json`).then((m) => m.default);

    initializeGT({ ...gtConfig, loadTranslations });
    ```

    Register [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), then use [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) from `gt-tanstack-start` inside the request scope. With [`localeRouting`](/docs/react/reference/config#locale-routing) enabled, middleware resolves the locale from the path prefix before the cookie and `Accept-Language` header.
  </Tab>

  <Tab value="React Native">
    Call [`initializeGT`](/docs/react/reference/config#initialize) once at app startup, spreading in your config.

    ```tsx
    import { initializeGT } from 'gt-react-native';
    import gtConfig from '../gt.config.json';

    const loadTranslations = (locale: string) =>
      import(`./_gt/${locale}.json`).then((m) => m.default);

    initializeGT({ ...gtConfig, loadTranslations });
    ```
  </Tab>
</Tabs>

## Add the provider [#provider]

Wrap your app in [`GTProvider`](/docs/react/reference/components/gt-provider#contracts) so components can read translations.

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    Load the active locale's translations on the server, then pass both values to the provider. The exact loader API depends on your framework.

    ```tsx title="src/routes/root.tsx"
    import { GTProvider, getTranslationsSnapshot, parseLocale } from 'gt-react';

    export async function loadRoot(request: Request) {
      const locale = parseLocale(request);
      return {
        locale,
        translations: await getTranslationsSnapshot(locale),
      };
    }

    export function Root({ locale, translations, children }) {
      return (
        <GTProvider locale={locale} translations={translations}>
          {children}
        </GTProvider>
      );
    }
    ```

    The provider also accepts [`region`](/docs/react/reference/components/gt-provider#region) and [`enableI18n`](/docs/react/reference/components/gt-provider#enable-i18n) (default `true`). When translation is disabled or the active locale equals the default locale, content renders in the source language.
  </Tab>

  <Tab value="Next.js">
    Wrap your root layout in [`<GTProvider>`](/docs/react/reference/components/gt-provider#contracts). It reads the request locale and translations from the plugin, so the App Router provider accepts only `children`.

    ```tsx title="app/layout.tsx"
    import { GTProvider, useLocale } from 'gt-next';

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      const locale = useLocale();
      return (
        <html lang={locale}>
          <body>
            <GTProvider>{children}</GTProvider>
          </body>
        </html>
      );
    }
    ```
  </Tab>

  <Tab value="TanStack Start">
    Pass the active [`locale`](/docs/react/reference/components/gt-provider#locale) and the [`translations`](/docs/react/reference/components/gt-provider#translations) for it. Both are required.

    ```tsx
    import { GTProvider, getTranslationsSnapshot } from 'gt-tanstack-start';

    const translations = await getTranslationsSnapshot(locale);

    <GTProvider locale={locale} translations={translations}>
      <App />
    </GTProvider>;
    ```
  </Tab>

  <Tab value="React Native">
    Wrap your app in [`<GTProvider>`](/docs/react/reference/components/gt-provider#contracts). It loads translations for the active locale itself, so it does not accept a `translations` prop; [`locale`](/docs/react/reference/components/gt-provider#locale) is optional and defaults to the stored or device locale.

    ```tsx
    import { GTProvider } from 'gt-react-native';

    <GTProvider>
      <App />
    </GTProvider>;
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Changed in v11 (React):** the `gt-react` provider no longer takes `config`, [`loadTranslations`](/docs/react/reference/functions/load-translations), or credentials as props. That setup now lives on the initialization call; the provider only receives the resolved [`locale`](/docs/react/reference/components/gt-provider#locale) and [`translations`](/docs/react/reference/components/gt-provider#translations).
</Callout>

See the [Configuration reference](/docs/react/reference/config) for all provider and initialization options.

## Add credentials [#credentials]

Translation delivery and development features use a project ID and API key, set through environment variables.

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    Expose the project ID and development API key through your framework's client environment-variable convention, then pass them to [`initializeGT`](/docs/react/reference/config#initialize). Never expose a production API key.
  </Tab>

  <Tab value="Next.js">
    Set them in your environment; the plugin reads them automatically. `GT_API_KEY` (the production key) is used server-side and by the CLI in CI. Use the `NEXT_PUBLIC_` prefix only for values that must reach the browser.

    ```bash title=".env.local"
    GT_PROJECT_ID="..."
    GT_DEV_API_KEY="gtx-dev-..."
    ```
  </Tab>

  <Tab value="TanStack Start">
    Set them through your bundler's public env and pass them into the initialization call.

    ```bash title=".env (Vite)"
    VITE_GT_PROJECT_ID="..."
    VITE_GT_DEV_API_KEY="gtx-dev-..."
    ```
  </Tab>

  <Tab value="React Native">
    Set them through your bundler's public env and pass them into the initialization call.

    ```bash title=".env (Expo)"
    EXPO_PUBLIC_GT_PROJECT_ID="..."
    EXPO_PUBLIC_GT_DEV_API_KEY="gtx-dev-..."
    ```
  </Tab>
</Tabs>

*Note: Only ever expose a development API key to the client. Production API keys are used by the CLI in CI, never shipped to the client.*

## Choose how translations are delivered [#delivery]

General Translation resolves translations in one of these modes, based on your configuration. This is the same across frameworks:

- **Local files:** provide [`loadTranslations`](/docs/react/reference/functions/load-translations) to import bundled JSON. See [Storing translations locally](/docs/react/guides/storing-translations).
- **General Translation CDN:** provide a [`projectId`](/docs/react/reference/config#project-id) (without a custom loader) to fetch translations from GT's CDN at runtime.
- **Custom endpoint:** set a custom [`cacheUrl`](/docs/react/reference/config#cache-url) to load from your own host.

In development, providing a [`projectId`](/docs/react/reference/config#project-id) and development API key enables on-demand translation and hot reload, so new strings translate as you work. In production, translations come from your pre-generated files or the CDN.

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations

## Sitemap

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