# Vue: Configuration
URL: https://generaltranslation.com/en-US/docs/vue/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
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` and `customMapping` are shared by every surface, while `locales` is 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 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 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` | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`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).

## Sitemap

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