# vue: GTPlugin
URL: https://generaltranslation.com/en-GB/docs/vue/reference/types/gt-plugin.mdx
---

title: GTPlugin
description: Install Vue translation state and imperatively control its locale and catalogue cache. API reference for GTPlugin.

---

[`createGT()`](/docs/vue/reference/functions/create-gt) and [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) return this Vue plugin. Its state and behaviour belong to the function that created it.

## Overview [#overview]

```ts
type GTPlugin = {
  getLocale(): string;
  install(app: App): void;
  loadTranslations(locale: string): Promise<TranslationCatalog>;
  setLocale(locale: string): Promise<void>;
};
```

| Method                                           | Description                                                                     | Return type                   |
| ------------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------------- |
| [`getLocale()`](#get-locale)                     | Return the locale currently managed by the plugin.                              | `string`                      |
| [`install(app)`](#install)                       | Provide the plugin&#39;s state to a Vue application.                            | `void`                        |
| [`loadTranslations(locale)`](#load-translations) | Preload and cache a locale without changing the active locale.                  | `Promise<TranslationCatalog>` |
| [`setLocale(locale)`](#set-locale)               | Change or persist the active locale according to the plugin&#39;s runtime mode. | `Promise<void>`               |

## `getLocale()` [#get-locale]

**Type** `() => string` · **Required**

For a [`createGT()`](/docs/vue/reference/functions/create-gt) plugin in the browser, this method reads the currently configured locale cookie and falls back to the plugin&#39;s explicit or default locale. On the server, it returns the instance-local value.

For an [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) plugin, it returns the locale pinned during page initialisation. Direct cookie changes do not affect the mounted SPA until the next reload and bootstrap.

## `install(app)` [#install]

**Type** `(app: App) => void` · **Required**

Provides translation state to components, formatters, and composables through Vue dependency injection. Calling `app.use(plugin)` calls this method.

Installation begins loading the active locale. A [`createGT()`](/docs/vue/reference/functions/create-gt) plugin can mount immediately with source content and re-render when loading succeeds. An [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) plugin is already preloaded when returned.

Install the exact SPA plugin returned by initialisation. Creating and installing a second plugin separates component lookups from module-level [`t()`](/docs/vue/reference/functions/t) lookups. A composable used without an installed plugin throws a diagnostic.

## `loadTranslations()` [#load-translations]

**Type** `(locale: string) => Promise<`[`TranslationCatalog`](/docs/vue/reference/types/translation-catalog)`>` · **Required**

Loads and caches a target catalogue without changing the active locale. The default locale returns its existing empty catalogue without calling the configured loader.

Successful results remain cached for this plugin, and concurrent calls for the same resolved locale share a promise. For an SPA plugin, locale aliases and supported-locale fallback are applied before loading.

A loader rejection is logged and rethrown. The failure is not cached, so a later call can retry.

## `setLocale()` [#set-locale]

**Type** `(locale: string) => Promise<void>` · **Required**

The transition depends on how the plugin was created:

* **[`createGT()`](/docs/vue/reference/functions/create-gt) plugin:** loads an uncached catalogue, then updates the cookie and reactive consumers. A rejected load leaves the existing locale and cookie unchanged. If calls overlap, only the latest request is applied.
* **[`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) plugin:** resolves the requested locale, writes the cookie, and reloads the document. It does not load the target catalogue or change the pinned locale on the current page before reloading.

[`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) provides this behaviour through the installed plugin.

## Example [#example]

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

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

await gt.loadTranslations('fr');
createApp(App).use(gt).mount('#app');

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