# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configuring a Rollup SPA
URL: https://generaltranslation.com/en-US/docs/react/guides/spa/configuring-rollup-spa.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How to configure gt-react in a Rollup-powered single-page React application.

Configure the application runtime and optionally bundle generated translation catalogs with your Rollup build.

This guide prepares the application runtime. Mark user-facing content for translation separately.

## React Rollup SPA setup [#setup]

Initialize `gt-react` before the application entry point runs.

### 1. Install gt-react

Install the latest `gt-react` with the repository's preferred package manager. Skip this step when it is already installed.

### 2. Add a `gt.config.json` file to the root of the project

Add a `gt.config.json` file to the root of the project. This file will contain the configuration for the `gt-react` package.

The locales already present in the project or supplied to the setup task are authoritative. Preserve any existing `locales` and `defaultLocale` values. The values below are examples only. If the project has no locale configuration, do not infer locale requirements from these examples.

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

The optional [`src`](/docs/cli/reference/config#src) field designates the source files GT scans for inline content; when omitted, it defaults to these JavaScript and TypeScript globs under `src`, `app`, `pages`, and `components`:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"],
  "src": [
    "src/**/*.{js,jsx,ts,tsx}",
    "app/**/*.{js,jsx,ts,tsx}",
    "pages/**/*.{js,jsx,ts,tsx}",
    "components/**/*.{js,jsx,ts,tsx}"
  ]
}
```

### 3. Initialize the library

Initialize the library with [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) before the application renders or imports modules that use module-level translation functions.

Create a bootstrap file next to the application's existing entry file. In this example, the original entry is `src/main.tsx` and the new bootstrap file is `src/index.ts`. Point Rollup's existing `input` configuration at the bootstrap file. Preserve all other build settings.

The bootstrap and translation loader import JSON files. If the project does not already configure JSON module support, install `@rollup/plugin-json` as a development dependency with the repository's preferred package manager and add it to the existing plugin list. Preserve every existing plugin and its configuration.

```js title="rollup.config.mjs"
import json from '@rollup/plugin-json';

export default {
  // ...the project's existing options
  input: 'src/index.ts',
  plugins: [
    // ...the project's existing plugins
    json(),
  ],
};
```

If the development HTML directly references the original source entry, update it too:

```html title="index.html"
<!-- <script type="module" src="/src/main.tsx"></script> -->
<script type="module" src="/src/index.ts"></script>
```

Then initialize GT and dynamically import the original entry only after initialization finishes. The Rollup reference application emits ESM and supports top-level await:

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

await initializeGTSPA(gtConfig);

await import('./main'); // render the app only after GT is ready
```

If the existing Rollup output format or target does not support top-level await, do not change it solely for this setup. Use an async bootstrap function instead:

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

async function bootstrap() {
  await initializeGTSPA(gtConfig);
  await import('./main');
}

void bootstrap();
```

## Loading translations [#translations]

When [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) is called without a [`loadTranslations`](/docs/react/reference/functions/load-translations) function, the runtime loads translations from the General Translation CDN only when a [`projectId`](/docs/react/reference/config#project-id) is available. To ship catalogs in the application bundle, configure an output path and a matching loader. The steps below use `src/_gt/[locale].json`.

### 1. Update the config

Set `files.gt.output` to the location where the CLI should write generated translation files.

Only add or merge the `files.gt.output` setting. Preserve the project's existing `locales` and `defaultLocale`; the values shown below remain examples and must not replace the project's configured locales.

Typically in a Rollup-powered application, the translations will be stored in the `src/_gt` directory. This allows Rollup to include the translation modules in the application bundle.

```json title="gt.config.json"
{
  "locales": ["fr", "zh"],
  "defaultLocale": "en",
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

### 2. Add the stubs

Create one empty JSON file for each target locale already configured in `gt.config.json`, excluding the default locale. These stubs let imports resolve before translation bundles exist. The `fr` and `zh` files below illustrate the example configuration from this guide; create files for the project's actual configured target locales instead. If no target locales are configured, do not invent locales or create placeholder files.

<Files>
  <Folder name="src">
    <Folder name="_gt">
      <File name="fr.json" />
      <File name="zh.json" />
    </Folder>
  </Folder>
</Files>

```json title="src/_gt/fr.json"
{}
```

```json title="src/_gt/zh.json"
{}
```

### 3. Add the loader

Create `src/loadTranslations.ts` to load the translations. It must resolve to the same output location configured in `files.gt.output`.

List every configured target locale explicitly in `translationLoaders`. Each loader must use a literal import path so Rollup can discover and emit every translation file at build time. The `fr` and `zh` entries below match this guide's example configuration; use the project's actual configured target locales instead.

```ts title="src/loadTranslations.ts"
const translationLoaders = {
  fr: () => import('./_gt/fr.json'),
  zh: () => import('./_gt/zh.json'),
};

export default async function loadTranslations(locale: string) {
  try {
    const loader =
      translationLoaders[locale as keyof typeof translationLoaders];
    if (!loader) {
      console.warn(`No translations found for locale "${locale}"`);
      return {};
    }
    const translations = await loader();
    return translations.default;
  } catch (error) {
    console.warn(`No translations found for locale "${locale}"`, error);
    return {};
  }
}
```

### 4. Update the initializer

Update the initializer to use the new loader function. Preserve whichever top-level-await or async-function bootstrap form the application uses.

```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');
```

## Next steps

- /docs/react/guides/spa/internationalizing-react-spa
- /docs/react/guides/developing-spa-translations
- /docs/react/guides/storing-translations
- /docs/react/guides/managing-locales

## Sitemap

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