# Vue: Configuring gt-vue
URL: https://generaltranslation.com/en-GB/docs/vue/guides/configuring.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How to create a Vue translation plugin, load catalogues, and configure browser or server rendering.

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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.