# vue: createGT
URL: https://generaltranslation.com/en-GB/docs/vue/reference/functions/create-gt.mdx
---

title: createGT
description: Create an isolated Vue translation plugin with reactive locale state and a catalogue cache. API reference for createGT.

---

Each call creates independent locale state, in-flight loads and cached catalogues. Use it for standard client applications, and create one instance per request for server-side rendering.

## Overview [#overview]

```ts
function createGT(options?: CreateGTOptions): GTPlugin;
```

[`createGT()`](#overview) returns immediately. Install the plugin using `app.use()`, or preload a locale with the returned [`GTPlugin`](/docs/vue/reference/types/gt-plugin) before rendering.

```ts
import { createApp } from 'vue';
import { createGT } from 'gt-vue';
import App from './App.vue';

const gt = createGT({
  defaultLocale: 'en',
  loadTranslations: async (locale) =>
    (await import(`./_gt/${locale}.json`)).default,
});

createApp(App).use(gt).mount('#app');
```

## Parameters [#parameters]

| Parameter | Description                                                | Type                                                             | Optional | Default |
| --------- | ---------------------------------------------------------- | ---------------------------------------------------------------- | -------- | ------- |
| `options` | Initial locale, cookie and catalogue loader configuration. | [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) | Yes      | `{}`    |

The `options` object accepts these fields:

| 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` | Browser cookie used to persist the locale.                            | `string`                                                          | Yes      | `generaltranslation.locale`  |

The default locale always renders source content, so its loader is never called. Unlike [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa), [`createGT()`](#overview) does not accept a `locales` allowlist or `customMapping`; the caller and loader determine which locale codes are available.

## Return value [#returns]

**Type** [`GTPlugin`](/docs/vue/reference/types/gt-plugin)

The returned plugin provides `install()`, `getLocale()`, `loadTranslations()`, and `setLocale()`. Install the same instance whose imperative methods you use.

This plugin is not connected to the browser-global state used by [`t()`](/docs/vue/reference/functions/t). A client application that needs module-level translations must instead install the exact plugin returned by [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa).

## How it works [#how-it-works]

* **Initial locale:** an explicit `locale` takes precedence over the browser cookie, which takes precedence over `defaultLocale`. On the server, there is no browser cookie. In a browser, an explicit locale is also written to the cookie to keep hydration consistent.
* **Initial load:** `app.use(gt)` starts loading the active target locale without blocking mounting. Source content renders until the catalogue arrives, then consumers that performed lookups re-render.
* **Caching:** successful catalogues are cached for the lifetime of the plugin. Concurrent requests for the same locale share one promise. The default locale is represented by source text and is already cached as an empty catalogue.
* **Locale changes:** `setLocale(locale)` loads an uncached catalogue before updating the cookie and reactive consumers. When locale requests overlap, only the latest request changes the active locale; successfully loaded earlier catalogues remain cached.
* **External cookie changes:** `getLocale()` reads the current browser cookie. Browsers do not emit a reactive cookie-change event, so changing `document.cookie` directly does not schedule a render; call the plugin setter or [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale).

If a loader rejects, the plugin logs a `gt-vue` diagnostic, rethrows the error and does not cache the failure. A rejected `setLocale()` retains the previous locale and cookie. The background load started by `install()` logs the failure but catches the rejection so the app can continue rendering source content.

## Server rendering [#server-rendering]

Create a new plugin for each request and explicitly pass the request locale. Await `loadTranslations(locale)` or `setLocale(locale)` before rendering:

```ts title="src/gt-server.ts"
import { createGT } from 'gt-vue';
import loadTranslations from './loadTranslations';

export async function createRequestGT(locale: string) {
  const gt = createGT({
    defaultLocale: 'en',
    locale,
    loadTranslations,
  });

  await gt.loadTranslations(locale);
  return gt;
}
```

Do not share this plugin across requests. Its locale and catalogue cache belong to a single application instance. Before hydration, create and preload a client plugin with the same explicit locale; hydrating against an unloaded catalogue can render source content and cause a mismatch.

## Example [#example]

Use the returned plugin methods outside a component when the host application manages locale changes:

```ts
const gt = createGT({ defaultLocale: 'en', loadTranslations });

await gt.loadTranslations('fr'); // preload without changing locale
await gt.setLocale('fr'); // uses the cached catalogue and rerenders consumers

console.log(gt.getLocale()); // "fr"
```