# vue: Configuring gt-vue
URL: https://generaltranslation.com/en-GB/docs/vue/guides/configuring.mdx
---
title: Configuring gt-vue
description: How to create a Vue translation plugin, load catalogues, and configure browser or server rendering.
related:
  links:
    - /docs/vue/guides/translating-content
    - /docs/vue/guides/translating-strings
    - /docs/vue/guides/managing-locales
    - /docs/vue/guides/storing-translations

---

Create one plugin for each isolated Vue application. The plugin manages its active locale, loaded catalogues, and reactive translation state.

Use [`createGT()`](/docs/vue/reference/functions/create-gt) for standard Vue applications, including apps that switch locales without reloading and apps that render on the server. Browser-only SPAs that require module-level [`t()`](/docs/vue/reference/functions/t) use a different startup path, described in [Developing with SPA translations](/docs/vue/guides/developing-spa-translations).

## Create the plugin [#create]

Pass the source locale and a [`loadTranslations`](/docs/vue/reference/types/load-translations) callback to [`createGT()`](/docs/vue/reference/functions/create-gt), then install the returned plugin with `app.use()`:

```ts title="src/main.ts"
import { createApp } from 'vue';
import { createGT } from 'gt-vue';
import App from './App.vue';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

const gt = createGT({
  defaultLocale: gtConfig.defaultLocale,
  loadTranslations,
});

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

Install that plugin once. Creating another instance gives it a separate locale and catalogue cache.

## Resolve the initial locale [#initial-locale]

[`createGT()`](/docs/vue/reference/functions/create-gt) resolves the initial locale in this order:

1. An explicit `locale` option.
2. The browser value of the configured locale cookie.
3. `defaultLocale`.

An explicit locale takes precedence during server rendering and hydration. In a browser, it replaces a stale cookie so the client starts with the same locale as the server.

```ts
const gt = createGT({
  defaultLocale: 'en',
  locale: serverLocale,
  localeCookieName: 'my-app.locale',
  loadTranslations,
});
```

The default cookie name is `generaltranslation.locale`. Change `localeCookieName` only if your router or server needs to share a different cookie.

## Load translation catalogues [#load]

The default locale renders directly from source content, so its loader is never called. Other locales are loaded through [`loadTranslations`](/docs/vue/reference/types/load-translations):

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

const loadTranslations: LoadTranslations = async (locale) => {
  try {
    return (await import(`./_gt/${locale}.json`)).default;
  } catch {
    return {};
  }
};

export default loadTranslations;
```

Successful catalogues are cached for the lifetime of the plugin, and concurrent requests for the same locale share a single load. On the client, the app can mount with source content while the first catalogue loads; translated components re-render when it arrives.

Returning an empty object uses source content as the fallback. If the callback rejects, locale changes are rejected and the current locale remains active.

## Keep CLI and runtime configuration aligned [#shared-config]

Use `gt.config.json` as the shared record of your source locale, target locales, and generated file location:

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

The CLI reads this file directly. [`createGT()`](/docs/vue/reference/functions/create-gt) accepts its own runtime options, so pass `defaultLocale` and your loader explicitly. The `locales` list remains useful for your language switcher and the CLI, but a reactive plugin does not reject other locale codes; your UI and loader determine which locales are available.

Production API credentials belong to the CLI process that generates translations. Do not expose `GT_API_KEY` in browser code.

## Configure server rendering [#ssr]

Create a new plugin for each request so locale and catalogue state cannot leak between users. Resolve the request locale, pass it explicitly and preload its catalogue 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;
}
```

Install the returned plugin on the request's Vue app. Before hydrating in the browser, create and preload a client plugin with the same explicit locale. Hydrating before the target catalogue is ready can briefly render source content and cause a mismatch.
## Next steps

- /docs/vue/guides/translating-content
- /docs/vue/guides/translating-strings
- /docs/vue/guides/managing-locales
- /docs/vue/guides/storing-translations