# General Translation Knowledge Base: Comment migrer de vue-i18n vers gt-vue ?
URL: https://generaltranslation.com/fr/kb/migrate-from-vue-i18n.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Installez gt-vue en parallèle de vue-i18n, synchronisez la locale active et migrez un composant à la fois en remplaçant les clés $t par du texte intégré dans `<T>` et useGT. General Translation traduit le texte migré en s’appuyant sur la structure de son modèle comme contexte, et votre équipe peut le corriger dans le tableau de bord. Les composants non migrés conservent leurs messages vue-i18n déjà relus.
Category: Internationalisation
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

vue-i18n affiche les traductions que vous rédigez dans un fichier de messages propre à chaque langue. gt-vue affiche le texte écrit directement dans vos modèles, et General Translation génère les traductions avec [`npx gt translate`](/docs/cli/reference/commands/translate). Migrer consiste à remplacer chaque recherche `$t('key')` par le texte source auquel elle renvoie, un composant à la fois, tandis que les deux plugins cohabitent dans la même application.

## Quelle est la correspondance entre les API de vue-i18n et celles de gt-vue ?

| vue-i18n                                           | gt-vue                                                                                                                                                                                                         |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createI18n({ locale, fallbackLocale, messages })` | [`createGT`](/docs/vue/reference/functions/create-gt)`({ defaultLocale, loadTranslations })`, avec les paramètres régionaux définis dans `gt.config.json`                                                      |
| `app.use(i18n)`                                    | `app.use(gt)`                                                                                                                                                                                                  |
| `$t('key')` dans les modèles                     | [`<T>`](/docs/vue/reference/components/t) autour du texte, ou une chaîne de caractères obtenue via [`useGT`](/docs/vue/reference/composables/use-gt)                                                           |
| `t('key')` dans `<script setup>`                   | `const gt = useGT()`, puis `gt('Inbox')` dans un `computed`                                                                                                                                                    |
| Interpolation nommée `{name}`                      | [`<Var>`](/docs/vue/reference/components/var) dans [`<T>`](/docs/vue/reference/components/t)                                                                                                                   |
| `<i18n-t keypath="...">` avec des slots            | [`<T>`](/docs/vue/reference/components/t) encapsulant directement le balisage                                                                                                                                  |
| `'no apples \| one apple \| {count} apples'`       | [`<Plural>`](/docs/vue/reference/components/plural) avec les slots `#zero`, `#singular` et `#plural`                                                                                                           |
| `n()` et `d()` avec des formats nommés             | [`<Num>`](/docs/vue/reference/components/num), [`<Currency>`](/docs/vue/reference/components/currency) et [`<DateTime>`](/docs/vue/reference/components/datetime), avec les options `Intl` passées directement |
| `locale.value = 'fr'`                              | [`useSetLocale`](/docs/vue/reference/composables/use-set-locale)`()('fr')` ; lisez la valeur avec [`useLocale`](/docs/vue/reference/composables/use-locale)                                                    |
| Chargement différé avec `setLocaleMessage`         | L’option `loadTranslations(locale)` charge chaque paramètre régional et le met en cache                                                                                                                        |
| `fallbackLocale`                                   | `defaultLocale` ; en l’absence de traduction, le texte source est affiché                                                                                                                                      |

Les clés de messages, les blocs personnalisés `<i18n>` des SFC et les messages liés (`@:key`) sont tous remplacés par du texte intégré : déplacez le texte de chaque message dans le modèle qui l’affiche, et écrivez les messages liés en toutes lettres.

## Étape 1 : installer gt-vue aux côtés de vue-i18n

gt-vue (actuellement en version 0.x) prend en charge Vue 3.3 et les versions ultérieures. Suivez le [Démarrage rapide Vue](/docs/vue/quickstart). En résumé :

1. Installez `gt-vue` ainsi que la CLI `gt` en tant que dépendance de développement.

2. Créez un fichier `gt.config.json` avec le même paramètre régional source et les mêmes locales cibles que votre configuration vue-i18n, ainsi qu&#39;un chemin de sortie, par exemple `src/_gt/[locale].json`.

3. Ajoutez une fonction `loadTranslations` et installez le plugin aux côtés de vue-i18n :

   ```ts title="src/main.ts"
   import { createApp } from 'vue';
   import { createGT, type LoadTranslations } from 'gt-vue';
   import App from './App.vue';
   import i18n from './i18n'; // votre instance createI18n existante

   const loadTranslations: LoadTranslations = async (locale) => {
     try {
       return (await import(`./_gt/${locale}.json`)).default;
     } catch {
       return {};
     }
   };

   createApp(App)
     .use(i18n)
     .use(createGT({ defaultLocale: 'en', loadTranslations }))
     .mount('#app');
   ```

4. Connectez-vous avec [`npx gt login`](/docs/cli/reference/commands/login) et définissez votre identifiant de projet.

gt-vue ne nécessite aucun plugin Vite : lorsque vous exécutez [`npx gt translate`](/docs/cli/reference/commands/translate), la CLI analyse les fichiers `.vue` à la recherche de [`<T>`](/docs/vue/reference/components/t) et de [`useGT`](/docs/vue/reference/composables/use-gt).

## Étape 2 : Conserver une seule locale active

Utilisez gt-vue comme sélecteur de langue, puis copiez son paramètre régional dans vue-i18n pour que les composants pas encore migrés suivent automatiquement :

```vue title="src/App.vue"
<script setup lang="ts">
import { watchEffect } from 'vue';
import { useI18n } from 'vue-i18n';
import { useLocale } from 'gt-vue';

const gtLocale = useLocale();
const { locale } = useI18n({ useScope: 'global' });

watchEffect(() => {
  locale.value = gtLocale.value;
});
</script>
```

Remplacez votre menu de langues par un contrôle qui appelle [`useSetLocale`](/docs/vue/reference/composables/use-set-locale). Avec [`createGT`](/docs/vue/reference/functions/create-gt), changer de langue charge les traductions du nouveau paramètre régional et réaffiche l&#39;interface sans recharger la page ; gt-vue enregistre ensuite ce choix dans le cookie `generaltranslation.locale`.

## Étape 3 : migrer un composant à la fois

Copiez le texte en langue source de votre fichier de messages dans le modèle. Avant :

```json title="src/locales/en.json"
{
  "greeting": "Hello, {name}!",
  "unread": "You have no messages | You have {count} message | You have {count} messages",
  "inbox": "Inbox"
}
```

```vue title="src/components/InboxHeader.vue"
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
defineProps<{ name: string; count: number }>();
const { t } = useI18n();
</script>

<template>
  <h1>{{ t('inbox') }}</h1>
  <p>{{ t('greeting', { name }) }}</p>
  <p>{{ t('unread', count) }}</p>
</template>
```

Après :

```vue title="src/components/InboxHeader.vue"
<script setup lang="ts">
import { computed } from 'vue';
import { T, Var, Num, Plural, useGT } from 'gt-vue';
defineProps<{ name: string; count: number }>();

const gt = useGT();
const title = computed(() => gt('Inbox')); // computed le maintient réactif aux changements de paramètre régional
</script>

<template>
  <h1>{{ title }}</h1>
  <T>
    <p>Hello, <Var>{{ name }}</Var>!</p>
    <p>
      <Plural :n="count">
        <template #zero>You have no messages</template>
        <template #singular>You have <Num :value="count" /> message</template>
        <template #plural>You have <Num :value="count" /> messages</template>
      </Plural>
    </p>
  </T>
</template>
```

À partir des slots `singular` et `plural`, General Translation génère les formes requises par chaque langue cible, comme `few` et `many` en russe, et [`<Plural>`](/docs/vue/reference/components/plural) sélectionne la bonne à l&#39;aide de `Intl.PluralRules`. Avec la syntaxe à barres verticales de vue-i18n, il faut définir une règle de pluralisation personnalisée pour ces langues. Le slot `zero` conserve votre formulation pour une boîte de réception vide. Utilisez [`useGT`](/docs/vue/reference/composables/use-gt) pour les chaînes statiques, comme les titres et les espaces réservés, et placez toute phrase contenant une valeur dynamique dans [`<T>`](/docs/vue/reference/components/t) avec [`<Var>`](/docs/vue/reference/components/var). Après chaque lot de composants, exécutez [`npx gt translate`](/docs/cli/reference/commands/translate) et vérifiez chaque paramètre régional.

## Qu&#39;advient-il de vos traductions existantes ?

Les composants que vous n&#39;avez pas encore migrés continuent d&#39;afficher leurs messages vue-i18n déjà relus : une migration progressive ne modifie donc que les écrans sur lesquels vous intervenez. gt-vue identifie les traductions par leur contenu source plutôt que par leur clé de message. Les textes que vous déplacez dans [`<T>`](/docs/vue/reference/components/t) ou [`useGT`](/docs/vue/reference/composables/use-gt) reçoivent donc de nouvelles traductions via [`npx gt translate`](/docs/cli/reference/commands/translate), générées en tenant compte du modèle environnant comme contexte. Le glossaire et les instructions personnalisées d&#39;un [groupe de contexte](/docs/platform/dashboard/guides/defining-context-for-translations) garantissent le respect de votre terminologie et de votre ton. Les relecteurs peuvent ensuite ajuster n&#39;importe quelle formulation depuis le [tableau de bord](/docs/platform/dashboard/guides/reviewing-translations).

## Étape 4 : supprimer vue-i18n

Lorsqu&#39;une recherche de `$t(`, `useI18n`, `<i18n-t` et `vue-i18n` ne renvoie plus aucun résultat, supprimez la configuration initiale de `createI18n`, les fichiers de messages, la synchronisation des paramètres régionaux et la dépendance `vue-i18n`. Ajoutez ensuite [`npx gt translate`](/docs/cli/reference/commands/translate) à votre processus de compilation ou à votre [CI](/kb/translations-in-ci) pour que les nouveaux textes soient livrés traduits à chaque livraison.

## Questions fréquentes

### gt-vue prend-il en charge Nuxt ?

gt-vue ne propose aucun module Nuxt et, contrairement à `@nuxtjs/i18n`, ne fournit ni routes localisées, ni balises hreflang, ni détection de la langue du navigateur. Le CLI analyse néanmoins les dossiers `pages/` et `layouts/` de Nuxt, et [`createGT`](/docs/vue/reference/functions/create-gt) peut afficher le rendu côté serveur à condition de créer un plugin par requête.

### gt-vue prend-il en charge les clés de message ?

Non. gt-vue traduit le texte intégré directement dans [`<T>`](/docs/vue/reference/components/t) et [`useGT`](/docs/vue/reference/composables/use-gt). Si les clés sont au cœur de votre workflow, conservez vue-i18n.

### Puis-je migrer un composant à la fois ?

Oui. Les deux plugins peuvent coexister dans la même application tant qu&#39;ils partagent la locale active. Supprimez vue-i18n une fois que plus aucun composant ne l&#39;utilise.

### gt-vue est-il gratuit ?

gt-vue est distribué sous licence MIT et affiche les traductions incluses dans le bundle sans nécessiter de compte. La génération de traductions avec General Translation est [facturée à l&#39;usage](https://generaltranslation.com/pricing).

## Points clés

* Exécutez gt-vue en parallèle de vue-i18n, changez de langue avec gt-vue et répercutez son paramètre régional dans vue-i18n jusqu’à la fin de la migration.
* Remplacez les clés `$t` par du texte intégré : [`<T>`](/docs/vue/reference/components/t) avec [`<Var>`](/docs/vue/reference/components/var) dans les modèles, les slots `singular` et `plural` de [`<Plural>`](/docs/vue/reference/components/plural) pour les formes plurielles à pipe, et [`useGT`](/docs/vue/reference/composables/use-gt) dans une propriété `computed` pour les chaînes statiques des scripts.
* Les composants non migrés conservent leurs messages vue-i18n déjà relus ; le texte migré est traduit avec son modèle comme contexte, puis relu dans le tableau de bord. Conservez vue-i18n si les clés de messages ou le routage de `@nuxtjs/i18n` sont au cœur de votre application.
* Supprimez vue-i18n lorsque plus rien ne l’utilise, puis exécutez [`npx gt translate`](/docs/cli/reference/commands/translate) dans votre CI.

## Related questions

- [General Translation ou vue-i18n : lequel choisir ?](https://generaltranslation.com/fr/kb/general-translation-vs-vue-i18n.mdx): General Translation permet aux équipes Vue d’écrire le texte source directement dans les modèles et de générer les traductions avec la CLI. Son plugin gt-vue affiche ce contenu avec une gestion des formes plurielles et un formatage des nombres adaptés au paramètre régional. Optez pour cette solution si vous ne voulez plus maintenir de fichiers sources à clés ; vue-i18n reste pertinent pour les équipes qui utilisent le module i18n de Nuxt et un workflow de catalogue bien établi.
- [Comment traduire une application Vue ?](https://generaltranslation.com/fr/kb/translate-vue-app.mdx): Traduire une application Vue consiste à faire passer chaque chaîne de caractères des modèles par une recherche dans la langue active, puis à la traduire dans chaque langue cible. Le plugin gt-vue de General Translation traduit le contenu encapsulé dans le composant `<T>`, et npx gt translate génère un catalogue par langue cible.
- [Comment maintenir les traductions à jour à chaque déploiement ?](https://generaltranslation.com/fr/kb/translations-in-ci.mdx): Exécutez la traduction comme une étape du pipeline avant chaque compilation de production, afin que les nouveaux textes soient livrés traduits avec le déploiement qui les ajoute. Le CLI gt de General Translation s’en charge avec npx gt translate, à l’aide d’une clé API de projet et d’un identifiant de projet stockés comme secrets CI.

## Previous and next questions

- Previous question: [Comment migrer de react-i18next vers gt-react ?](https://generaltranslation.com/fr/kb/migrate-from-react-i18next.mdx)
- Next question: [Agent de codage IA ou pipeline de traduction : lequel doit automatiser votre localisation ?](https://generaltranslation.com/fr/kb/ai-coding-agent-vs-translation-pipeline.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.