# Vue: Quickstart
URL: https://generaltranslation.com/en-GB/docs/vue/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Add multiple languages to a Vue application in under 10 minutes.

By the end of this guide, your Vue app will display content in multiple languages and allow users to change the active locale without reloading the page.

`gt-vue` runs as a Vue plugin. The plugin loads each translation catalogue once, caches it, and reactively rerenders translated content when the locale changes.

**Prerequisites:**

* A Vue 3 application running version 3.3 or later
* Node.js `^20.19.0 || >=22.12.0` for the current Vite toolchain

<Callout type="info">
  **0.x package:** `gt-vue` is unstable. Its API and behaviour may change between releases independently of the stable React packages.
</Callout>

## Quickstart [#quickstart]

### 1. Install the packages

`gt-vue` powers translations in your app. [`gt`](/docs/cli/quickstart) extracts your source content and generates translation catalogues.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-vue
    npm install --save-dev gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-vue
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-vue
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-vue
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 2. Create a translation config file

Create `gt.config.json` in your project root. Set the locale of your source content, the locales to translate into, and the output path for generated catalogues.

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

* `defaultLocale` is the language of your source content.
* `locales` lists the target languages. Choose any locale from the [supported locales list](/docs/platform/dashboard/reference/supported-locales).
* `files.gt.output` tells the CLI where to write each catalogue. Keep the `[locale]` placeholder in the path.

### 3. Create a translation loader

Create a loader that returns the generated catalogue for the requested locale:

```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 loader is not called for the default locale because your source content already serves as its catalogue. Returning an empty object lets the app render source content when a target catalogue is unavailable.

### 4. Register the plugin

Create a [`createGT()`](/docs/vue/reference/functions/create-gt) plugin and install it before mounting your app:

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

The plugin uses the saved locale cookie when available; otherwise, it starts with `defaultLocale`. It mounts immediately with source content, then updates reactively when the requested catalogue finishes loading.

### 5. Mark content for translation

Use [`<T>`](/docs/vue/reference/components/t) for rich template content and [`useGT()`](/docs/vue/reference/composables/use-gt) for standalone strings, such as input attributes:

```vue title="src/App.vue"
<script setup lang="ts">
import { T, useGT } from 'gt-vue';

const gt = useGT();
</script>

<template>
  <main>
    <T>
      <h1>Welcome to my app</h1>
      <p>This content will be translated automatically.</p>
    </T>

    <input :placeholder="gt('Search products')" />
  </main>
</template>
```

Keep content inside [`<T>`](/docs/vue/reference/components/t) static. Use [variable and branching components](/docs/vue/guides/formatting-variables) for runtime values and conditional alternatives.

### 6. Add a language switcher

Read the current locale with [`useLocale()`](/docs/vue/reference/composables/use-locale) and change it with [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale):

```vue title="src/App.vue"
<script setup lang="ts">
import { T, useGT, useLocale, useSetLocale } from 'gt-vue';
import gtConfig from '../gt.config.json';

const gt = useGT();
const locale = useLocale();
const setLocale = useSetLocale();
const locales = [gtConfig.defaultLocale, ...gtConfig.locales];

async function changeLocale(event: Event) {
  const target = event.target as HTMLSelectElement;
  await setLocale(target.value);
}
</script>

<template>
  <main>
    <label>
      Language
      <select :value="locale" @change="changeLocale">
        <option v-for="code in locales" :key="code" :value="code">
          {{ code }}
        </option>
      </select>
    </label>

    <T>
      <h1>Welcome to my app</h1>
      <p>This content will be translated automatically.</p>
    </T>

    <input :placeholder="gt('Search products')" />
  </main>
</template>
```

[`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) loads a missing catalogue before saving the locale cookie and re-rendering reactive consumers. With the loader above, a missing file returns an empty catalogue, changes the locale and renders source content. If a loader rejects instead, the current locale remains active.

### 7. Authenticate and translate

Authenticate with General Translation:

```bash
npx gt auth
```

The command guides you through signing in and creating credentials. Keep the generated production API key in your local environment file and out of browser code and version control.

Then generate the translation catalogues:

```bash
npx gt translate
```

The CLI scans your Vue source, translates the extracted content, and writes one JSON file per target locale to `src/_gt/`. Run the command again whenever your source content changes.

### 8. Run and verify

Start the application:

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun run dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

Open the local URL shown by your development server. Choose `es`, `fr`, or `ja` from the language selector and confirm that the heading and search placeholder display translated text.

## Troubleshooting [#troubleshooting]

<Accordions>
  <Accordion title="The app remains in the source locale">
    The active locale is stored in the `generaltranslation.locale` cookie. Clear any stale cookie, then select the target locale again. Also confirm that its JSON file exists under `src/_gt/` and that the loader returns its default export.
  </Accordion>

  <Accordion title="A translated string does not update after changing locales">
    Call the function returned by [`useGT()`](/docs/vue/reference/composables/use-gt) from the template or a Vue computed value. A string translated once during setup is a snapshot and does not run again when reactive locale state changes.
  </Accordion>
</Accordions>

## 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.