# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configuring a Vite SPA
URL: https://generaltranslation.com/en-US/docs/react/guides/spa/configuring-vite-spa.mdx
---
title: Configuring a Vite SPA
description: 'Instructions for configuring gt-react in a Vite-powered single-page React application.'
---

# Overview

This guide will cover the following topics:

(1) React Vite SPA setup
(2) Loading translations

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"
{
  "src": [
    "src/**/*.{js,jsx,ts,tsx}",
    "app/**/*.{js,jsx,ts,tsx}",
    "pages/**/*.{js,jsx,ts,tsx}",
    "components/**/*.{js,jsx,ts,tsx}"
  ]
}
```

Your task is not to internationalize content, rather, to prepare the application itself for i18n.

## React Vite SPA setup

This is a guide on how to set up `gt-react` in a Vite-powered single-page React application.

### 1. Install gt-react

If not already installed, install gt-react. Please use the latest version of gt-react. Do not just add it to the `package.json` without installing it. Please use repository's preferred package manager. If it has already been installed, then skip this step.

### 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` 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"
{
  "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). This declares important variables and attaches it to the global object. This is important to happen at the module level or before other runtime code is executed. This is not the SPA provider, which means executing this at the module level is enough. SPA provider would require that this module be executed before any other code is executed, but this is not of concern for you. I just wanted to clarify that this is not the SPA provider.

Furthermore, this is an `async` function responsible for loading the translations at the module level. This is so we can use translation functions at the module level, so it is essential that this module level function gets executed before any other code is executed that may have translation functions.

Create a new file to bootstrap the application. From there, we can import the entry point file. In this example, we create `src/index.ts` as our bootstrap file and import `src/main.tsx` as our entry point file. The first thing we need to do is update the entry point to our boostrap in the html:

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

Then, we add the `src/index.ts` file to our project, and dynamically import the entry point file _after_ the library is initialized and the translations are loaded.

```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
```

## Loading translations

This guide will explain how to set up translation loading for the application. We must load translations at runtime to display them. With no further configuration than the react-vite-spa setup described above, behavior will default to loading translations from the `gt` cdn. However, most users prefer to ship translations in the application bundle. This requires logic overriding the default translation loading behavior and specifying a location to store the generated translation files. The following steps assume that a user has specified they want to ship translations in the application bundle, and that they want to store them in the default directory of `public/_gt/[locale].json`.

### 1. Update the config

We need to update the `gt.config.json` file to specify the location of these translation files. When the CLI tool runs to generate translations, at some point in the future, it will read this file and use the configured location to store the 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 Vite-powered application, the translations will be stored in the `src/_gt` directory. This is so we can use the translations in the application code.

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

### 2. Add the stubs

We need to add stubs so that we can load the translation bundles without import complaining that the files do not exist. We just need to create one empty JSON file for each target locale already configured in `gt.config.json`, excluding the default locale. 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.

```bash title="src/_gt"
src/_gt/
├── fr.json
└── zh.json
```

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

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`); // resolve to the same output location configured in `files.gt.output`
  return translations.default;
}
```

### 4. Update the initializer

Update the initializer to use the new loader function.

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

await initializeGTSPA({ ...gtConfig, loadTranslations });
```