# vue: Configuration
URL: https://generaltranslation.com/en-US/docs/vue/reference/config.mdx
---

title: Configuration
description: Configure catalog generation and runtime initialization for a Vue application. Reference for Vue configuration.

---

Configuration has two independent consumers. The `gt` CLI reads `gt.config.json` to find source content and write catalogs, while your application passes runtime options to [`createGT()`](/docs/vue/reference/functions/create-gt) or [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa).

`gt-vue` does not find or read `gt.config.json` automatically. Import shared values explicitly, and provide functions such as [`loadTranslations`](/docs/vue/reference/types/load-translations) in application code.

## Overview [#overview]

| Surface | Purpose | Configuration |
| --- | --- | --- |
| `gt.config.json` | Extract source content and generate translation catalogs. | JSON-serializable CLI fields such as `projectId`, `defaultLocale`, `locales`, `src`, `files`, and `customMapping`. |
| [`createGT()`](/docs/vue/reference/functions/create-gt) | Create an isolated plugin for reactive client rendering or request-scoped server rendering. | [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) |
| [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | Create and preload the browser-global plugin used by module-level [`t()`](/docs/vue/reference/functions/t). | [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) |

The CLI-only fields `projectId`, `src`, and `files` are ignored by the runtime. The runtime-only fields `locale`, `localeCookieName`, and `loadTranslations` cannot be represented fully in JSON. `defaultLocale` is shared by every surface; `locales` and `customMapping` are also accepted by the SPA initializer.

## `gt.config.json` [#config-file]

Place `gt.config.json` at the project root. This Vue configuration scans explicit source globs and writes one catalog for each target locale:

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "src": ["src/**/*.{vue,js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

`src` entries are glob patterns. A bare directory such as `"src"` is not a recursive file match; include the files and extensions the CLI should scan. The Vue defaults cover root single-file components and conventional Vue and Nuxt directories when `src` is omitted.

| Field | Vue usage | Runtime usage |
| --- | --- | --- |
| `$schema` | Adds editor validation and completion. | None |
| `projectId` | Selects the General Translation Project used by the CLI. | None |
| [`defaultLocale`](/docs/cli/reference/config#default-locale) | Declares the source locale. | Pass to either runtime initializer. |
| [`locales`](/docs/cli/reference/config#locales) | Declares the target locales generated by the CLI. | Pass to [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) to reject unsupported saved or requested locales. A [`createGT()`](/docs/vue/reference/functions/create-gt) plugin does not restrict locale codes. |
| [`src`](/docs/cli/reference/config#src) | Selects Vue, JavaScript, and TypeScript source files for extraction. | None |
| [`files.gt.output`](/docs/cli/reference/config#files) | Sets the generated catalog path. Keep the `[locale]` placeholder. | Make the loader import from the same directory. |
| [`customMapping`](/docs/cli/reference/config#custom-mapping) | Applies locale aliases during translation generation. | Pass to [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) so object mappings with a valid `code` can drive locale matching and formatter locale resolution. |

See the [CLI configuration reference](/docs/cli/reference/config) for all project, file, publishing, review, and branch fields. Keep `GT_API_KEY` in the CLI environment; do not put production credentials in `gt.config.json` or browser code.

## Runtime options [#runtime-options]

| Option | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | Default |
| --- | --- | --- | --- |
| `defaultLocale` | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | `en` |
| `loadTranslations` | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | Empty catalog |
| `locale` | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | Browser cookie, then `defaultLocale` |
| `localeCookieName` | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | `generaltranslation.locale` |
| `locales` | No | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | Unrestricted |
| `customMapping` | No | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | None |

Use [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) and [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) for the complete option contracts. Passing `{ ...gtConfig, loadTranslations }` to the SPA initializer is supported: it consumes the overlapping fields and ignores other CLI fields at runtime.

## Catalog loading [#catalog-loading]

The output path and loader path must describe the same files:

```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;
```

The default locale uses source text and never calls the loader. Successful target catalogs are cached per plugin, and concurrent requests for one locale share a promise. A rejected loader call is logged and rethrown; it is not cached, so a later call can retry.

Installing a [`createGT()`](/docs/vue/reference/functions/create-gt) plugin starts its initial load in the background and renders source content until the catalog arrives. [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) instead awaits the initial load before it returns.

## Reactive setup [#reactive-setup]

Use [`createGT()`](/docs/vue/reference/functions/create-gt) for an ordinary client application. Pass runtime fields explicitly because `locales`, `src`, and `files` are not [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options):

```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');
```

For server-side rendering, create a new plugin for every request, pass the request locale explicitly, and preload it 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;
}
```

Use the same explicit locale and a preloaded catalog before hydrating the client. A shared server plugin can leak locale and catalog state across requests.

## Browser SPA [#browser-spa]

Use [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) only in a browser-only single-page application that calls [`t()`](/docs/vue/reference/functions/t) at module scope. Await initialization before dynamically importing application modules, 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);
});
```

The first call owns the page-wide runtime. Locale changes update the cookie and reload the document, allowing module-level translations to run again with the newly preloaded catalog. For reactive locale changes without a reload, use [`createGT()`](/docs/vue/reference/functions/create-gt) and translate component strings with [`useGT()`](/docs/vue/reference/composables/use-gt).