# vue: createGT
URL: https://generaltranslation.com/fr/docs/vue/reference/functions/create-gt.mdx
---

title: createGT
description: Crée un plugin de traduction Vue isolé avec un état de paramètres régionaux réactif et un cache de catalogues. Référence de l’API createGT.

---

Chaque appel crée un état de paramètres régionaux indépendant, des chargements en cours et des catalogues mis en cache. Utilisez-le pour les applications clientes classiques et créez une instance par requête pour le rendu côté serveur.

## Vue d’ensemble [#overview]

```ts
function createGT(options?: CreateGTOptions): GTPlugin;
```

[`createGT()`](#overview) renvoie immédiatement. Installez le plugin avec `app.use()` ou préchargez un paramètre régional à l’aide du [`GTPlugin`](/docs/vue/reference/types/gt-plugin) renvoyé avant le rendu.

```ts
import { createApp } from 'vue';
import { createGT } from 'gt-vue';
import App from './App.vue';

const gt = createGT({
  defaultLocale: 'en',
  loadTranslations: async (locale) =>
    (await import(`./_gt/${locale}.json`)).default,
});

createApp(App).use(gt).mount('#app');
```

## Paramètres [#parameters]

| Paramètre | Description                                                                        | Type                                                             | Facultatif | Par défaut |
| --------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------- | ---------- |
| `options` | Configuration initiale du paramètre régional, du cookie et du loader de catalogue. | [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) | Oui        | `{}`       |

L’objet `options` accepte les champs suivants :

| Option             | Description                                                                   | Type                                                              | Facultatif | Par défaut                   |
| ------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------- | ---------------------------- |
| `defaultLocale`    | Paramètre régional source et de secours.                                      | `string`                                                          | Oui        | `en`                         |
| `loadTranslations` | Loader asynchrone du catalogue cible.                                         | [`LoadTranslations`](/docs/vue/reference/types/load-translations) | Oui        | Catalogue vide               |
| `locale`           | Paramètre régional initial explicite. Il prévaut sur le cookie du navigateur. | `string`                                                          | Oui        | Cookie, puis `defaultLocale` |
| `localeCookieName` | Cookie du navigateur utilisé pour conserver le paramètre régional.            | `string`                                                          | Oui        | `generaltranslation.locale`  |

Le paramètre régional par défaut affiche toujours le contenu source ; son loader n’est donc jamais appelé. Contrairement à [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa), [`createGT()`](#overview) n’accepte ni liste `locales` des paramètres régionaux autorisés ni `customMapping` ; l’appelant et le loader déterminent les codes de langue utilisables.

## Valeur de retour [#returns]

**Type** [`GTPlugin`](/docs/vue/reference/types/gt-plugin)

Le plugin renvoyé fournit `install()`, `getLocale()`, `loadTranslations()` et `setLocale()`. Installez la même instance que celle dont vous utilisez les méthodes impératives.

Ce plugin n'est pas connecté à l'état global du navigateur utilisé par [`t()`](/docs/vue/reference/functions/t). Une application cliente nécessitant des traductions au niveau du module doit plutôt installer le plugin exact renvoyé par [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa).

## Fonctionnement [#how-it-works]

* **Paramètre régional initial :** un `locale` explicite prévaut sur le cookie du navigateur, lui-même prioritaire sur `defaultLocale`. Côté serveur, il n’y a pas de cookie de navigateur. Dans le navigateur, un paramètre régional explicite est également enregistré dans le cookie afin de garantir la cohérence de l’hydratation.
* **Chargement initial :** `app.use(gt)` commence à charger le paramètre régional cible actif sans bloquer le montage. Le contenu source s’affiche jusqu’à l’arrivée du catalogue, puis les consommateurs ayant effectué des recherches sont réaffichés.
* **Mise en cache :** les catalogues chargés avec succès sont mis en cache pendant toute la durée de vie du plugin. Les requêtes simultanées pour un même paramètre régional partagent une même promesse. Le paramètre régional par défaut est représenté par le texte source et est déjà mis en cache sous la forme d’un catalogue vide.
* **Changements de paramètre régional :** `setLocale(locale)` charge un catalogue absent du cache avant de mettre à jour le cookie et les consommateurs réactifs. Lorsque des requêtes de paramètres régionaux se chevauchent, seule la plus récente modifie le paramètre régional actif ; les catalogues précédemment chargés avec succès restent en cache.
* **Modifications externes du cookie :** `getLocale()` lit le cookie actuel du navigateur. Les navigateurs n’émettent pas d’événement réactif lors d’un changement de cookie ; modifier directement `document.cookie` ne déclenche donc pas d’affichage. Appelez le setter du plugin ou [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale).

Si un loader échoue, le plugin consigne un diagnostic `gt-vue`, propage de nouveau l’erreur et ne met pas l’échec en cache. Un `setLocale()` rejeté conserve le paramètre régional et le cookie précédents. Le chargement en arrière-plan lancé par `install()` consigne l’échec, mais intercepte le rejet afin que l’application puisse continuer à afficher le contenu source.

## Rendu côté serveur [#server-rendering]

Créez une nouvelle instance du plugin pour chaque requête et transmettez explicitement le paramètre régional de la requête. Attendez `loadTranslations(locale)` ou `setLocale(locale)` avant le rendu :

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

Ne partagez pas ce plugin entre les requêtes. Son paramètre régional et le cache de son catalogue sont propres à une instance d’application. Avant l’hydratation, créez et préchargez un plugin client avec le même paramètre régional explicite ; une hydratation avec un catalogue non chargé peut afficher le contenu source et entraîner une incohérence.

## Exemple [#example]

Utilisez les méthodes renvoyées par le plugin en dehors d’un composant lorsque l’application hôte gère les changements de paramètre régional :

```ts
const gt = createGT({ defaultLocale: 'en', loadTranslations });

await gt.loadTranslations('fr'); // précharge sans changer le paramètre régional
await gt.setLocale('fr'); // utilise le catalogue mis en cache et réaffiche les consommateurs

console.log(gt.getLocale()); // "fr"
```