# Vue: Configuration
URL: https://generaltranslation.com/en-GB/docs/vue/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Configure catalogue generation and runtime initialisation for a Vue application. Vue configuration reference.

Configuration has two independent consumers. The `gt` CLI reads `gt.config.json` to find source content and write catalogues, 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 automatically locate or read `gt.config.json`. Explicitly import shared values and provide functions such as [`loadTranslations`](/docs/vue/reference/types/load-translations) in your application code.

## Overview [#overview]

| Surface                                                                | Purpose                                                                                                     | Configuration                                                                                                      |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `gt.config.json`                                                       | Extract source content and generate translation catalogues.                                                 | JSON-serialisable 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 fully represented in JSON. `defaultLocale` and `customMapping` are shared across all surfaces, while `locales` is accepted by the SPA initialiser.

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

Place `gt.config.json` at the project root. This Vue configuration scans explicit source globs and writes one catalogue 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 initialiser.                                                                                                                                                                                                                                            |
| [`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 catalogue 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 either runtime. [`createGT()`](/docs/vue/reference/functions/create-gt) uses object mappings with a valid `code` for formatting and plural rules; [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) also uses them for supported-locale matching. |

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.

## Vue extraction [#vue-extraction]

Vue template compiler settings affect extracted content and its translation hash. The extractor discovers these settings from the active Vite or Nuxt configuration by default. Configure them explicitly when automatic discovery is ambiguous or your application uses custom values:

| Option                                                | Description                                           | Type                       | Optional | Default                                 |
| ----------------------------------------------------- | ----------------------------------------------------- | -------------------------- | -------- | --------------------------------------- |
| `files.gt.parsingFlags.vueCompilerOptions.whitespace` | Matches Vue's template whitespace handling.       | `'condense' \| 'preserve'` | Yes      | Discovered setting, then Vue default    |
| `files.gt.parsingFlags.vueCompilerOptions.delimiters` | Matches custom template interpolation delimiters.     | `[string, string]`         | Yes      | Discovered setting, then `['{{', '}}']` |
| `files.gt.parsingFlags.viteConfigPath`                | Selects one Vite config relative to the project root. | `string`                   | Yes      | Automatic discovery                     |

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "parsingFlags": {
        "vueCompilerOptions": {
          "whitespace": "preserve",
          "delimiters": ["${", "}"]
        },
        "viteConfigPath": "config/vite.app.ts"
      }
    }
  }
}
```

Keep these values identical to the application compiler. Changing whitespace or delimiters can change source content and invalidate existing translation hashes.

For TypeScript or JavaScript path aliases, pass the config file to the CLI:

```bash
npx gt translate --tsconfig config/tsconfig.app.json
```

`--tsconfig` and its `--jsconfig` alias are command-line options, not fields in `gt.config.json`. When omitted, extraction discovers the nearest available config.

## 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 catalogue                      |
| `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`    | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | None                                 |

See [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) and [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) for the full option contracts. You can pass `{ ...gtConfig, loadTranslations }` to the SPA initialiser: it uses the overlapping fields and ignores other CLI fields at runtime.

## Catalogue loading [#catalog-loading]

The output path and loader path must refer to 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 catalogues are cached per plugin, and concurrent requests for a locale share a promise. A rejected loader call is logged and rethrown; it is not cached, so a subsequent 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 catalogue arrives. [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) instead awaits the initial load before returning.

## Reactive setup [#reactive-setup]

Use [`createGT()`](/docs/vue/reference/functions/create-gt) for a standard client application. Pass runtime fields explicitly, as `locales`, `src`, and `files` are not part of [`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 each request, explicitly pass the request locale, 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 catalogue before hydrating the client. A shared server plugin can leak locale and catalogue 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 initialisation 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 catalogue. 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).

## Sitemap

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