# vue: useSetLocale
URL: https://generaltranslation.com/en-GB/docs/vue/reference/composables/use-set-locale.mdx
---

title: useSetLocale
description: Change the active locale. API reference for useSetLocale.

---

The `useSetLocale` composable returns the installed plugin's asynchronous locale setter. Its loading and navigation behaviour depend on how the plugin was created.

## Overview [#overview]

Call the returned function with the target locale:

```vue
<script setup lang="ts">
import { useSetLocale } from 'gt-vue';

const setLocale = useSetLocale();
</script>

<template>
  <button @click="setLocale('fr')">Français</button>
</template>
```

Use [`useLocale()`](/docs/vue/reference/composables/use-locale) to read the active locale.

## How it works [#how-it-works]

### Reactive plugins

For a [`createGT()`](/docs/vue/reference/functions/create-gt) plugin, the setter:

1. Loads an uncached target catalogue through the configured loader.
2. Saves the target locale in the configured cookie after loading succeeds.
3. Updates reactive consumers without reloading the page.

Successfully loaded catalogues remain cached. Concurrent requests can finish in any order, but only the latest request changes the active locale. If its catalogue load rejects, the promise rejects and the current locale and cookie remain unchanged.

### Browser SPA plugins

For the singleton returned by [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa), the setter resolves the requested locale against the configured locale list, if one is provided, writes the cookie and reloads the document. It does not load the target catalogue on the current page, whose locale remains pinned until the reload. Reloading allows module-level [`t()`](/docs/vue/reference/functions/t) calls to run again after the new catalogue has been preloaded.

## Parameters [#parameters]

`useSetLocale` takes no parameters.

## Returns [#returns]

**Type** `(locale: string) => Promise<void>`

An asynchronous setter with this parameter:

| Parameter           | Description         | Type     | Optional | Default |
| ------------------- | ------------------- | -------- | -------- | ------- |
| [`locale`](#locale) | Target locale code. | `string` | No       | —       |

### `locale`

**Type** `string` · **Required**

The target locale code. A reactive [`createGT()`](/docs/vue/reference/functions/create-gt) plugin accepts any code its loader can handle. When an [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) plugin has a configured `locales` list, it matches those locales and configured aliases, falling back to its default locale if the request is unsupported.

## Example [#example]

Await reactive changes when subsequent code depends on the new locale:

```vue title="LocaleSelect.vue"
<script setup lang="ts">
import { useLocale, useSetLocale } from 'gt-vue';

const locale = useLocale();
const setLocale = useSetLocale();

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

<template>
  <select :value="locale" @change="changeLocale">
    <option value="en">English</option>
    <option value="fr">Français</option>
    <option value="ja">日本語</option>
  </select>
</template>
```

In an SPA initialised with [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa), the document reload begins as part of the call, so do not schedule same-page work that assumes the target locale is already active.