# vue: initializeGTSPA
URL: https://generaltranslation.com/en-GB/docs/vue/reference/functions/initialize-gt-spa.mdx
---

title: initializeGTSPA
description: Initialise and preload the browser-only Vue SPA runtime for module-level translations. API reference for initializeGTSPA.

---

This initialiser owns a single page-wide runtime and makes its loaded catalogue available to synchronous [`t()`](/docs/vue/reference/functions/t) calls. It complements the [`useGT()`](/docs/vue/reference/composables/use-gt) callback inside components; it does not replace the composable or support server rendering.

## Overview [#overview]

```ts
function initializeGTSPA(
  options?: InitializeGTSPAOptions
): Promise<GTPlugin>;
```

Await the initialiser before importing any module that calls [`t()`](/docs/vue/reference/functions/t), then install the exact returned plugin:

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

async function bootstrap() {
  const gt = await initializeGTSPA({ ...gtConfig, loadTranslations });
  const { mount } = await import('./main');
  mount(gt);
}

void bootstrap().catch((error: unknown) => {
  console.error(error);
});
```

## Parameters [#parameters]

| Parameter | Description                                                                 | Type                                                                            | Optional | Default |
| --------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------- | ------- |
| `options` | SPA locale, cookie, mapping, allowlist, and catalogue loader configuration. | [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) | Yes      | `{}`    |

| Option             | Description                                                                            | Type                                                                  | Optional | Default                      |
| ------------------ | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------- | ---------------------------- |
| `defaultLocale`    | Source and fallback locale.                                                            | `string`                                                              | Yes      | `en`                         |
| `loadTranslations` | Asynchronous target-catalogue loader.                                                  | [`LoadTranslations`](/docs/vue/reference/types/load-translations)     | Yes      | Empty catalogue              |
| `locale`           | Explicit initial locale. It takes precedence over the browser cookie.                  | `string`                                                              | Yes      | Cookie, then `defaultLocale` |
| `localeCookieName` | Cookie used to persist locale selection.                                               | `string`                                                              | Yes      | `generaltranslation.locale`  |
| `locales`          | Target locales accepted from configuration, cookies, and setters.                      | `readonly string[]`                                                   | Yes      | Unrestricted                 |
| `customMapping`    | Object mapping `code` values used for locale matching and formatter locale resolution. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes      | None                         |

`locales` normally contains the target locales from `gt.config.json`; the initialiser adds `defaultLocale` to the supported set. See [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) for resolution details.

## Initialisation [#initialization]

The first call starts page-wide initialisation and owns its options. Concurrent calls share that promise. Once it succeeds, every subsequent call returns the same [`GTPlugin`](/docs/vue/reference/types/gt-plugin) and ignores any new options.

Initialisation performs these steps before resolving:

1. Resolve the explicit locale, saved cookie or default locale against `locales` and `customMapping`.
2. Create a runtime whose active locale remains pinned for the lifetime of the page.
3. Load and cache the active target catalogue. The default locale uses source content and skips the loader.
4. Publish the runtime to module-level [`t()`](/docs/vue/reference/functions/t) calls.

If loading rejects, initialisation logs the loader diagnostic and rejects. The failed attempt does not become the singleton, so a later call can retry.

## Locale changes [#locale-changes]

The returned plugin uses a reload transition. Calling `plugin.setLocale(locale)` or [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) resolves the requested locale, writes it to the configured cookie, and reloads the document.

The current page remains on its pinned locale until it reloads. The next bootstrap resolves the new cookie and preloads that catalogue before application modules run, so every module-level translation is evaluated again. The setter does not load the target catalogue into the current page before reloading.

If `locales` is provided, matching is case-insensitive and supports canonical aliases. The spelling from `gt.config.json` is preserved for loader paths. Unsupported saved or requested locales resolve to `defaultLocale`. When `locales` is omitted, non-default locale codes remain unrestricted.

## Return and errors [#return-errors]

**Returns** `Promise<`[`GTPlugin`](/docs/vue/reference/types/gt-plugin)`>`

The promise resolves only once the initial locale is ready. Install this exact plugin; creating a separate [`createGT()`](/docs/vue/reference/functions/create-gt) instance would give components a different locale and catalogue cache from [`t()`](/docs/vue/reference/functions/t).

The returned promise rejects in a server-rendered environment because browser-global state and document reloads are not request-safe. For server rendering, use a request-scoped [`createGT({ locale })`](/docs/vue/reference/functions/create-gt#server-rendering) plugin and [`useGT()`](/docs/vue/reference/composables/use-gt) inside components.

## Example [#example]

Keep the normal Vue entry point behind a mount function:

```ts title="src/main.ts"
import { createApp } from 'vue';
import type { GTPlugin } from 'gt-vue';
import App from './App.vue';

export function mount(gt: GTPlugin) {
  createApp(App).use(gt).mount('#app');
}
```

Any module reached through the subsequent dynamic import can then translate during evaluation:

```ts title="src/navigation.ts"
import { t } from 'gt-vue';

export const navigation = [
  { label: t('Documentation'), href: '/docs' },
  { label: t('Settings'), href: '/settings' },
];
```