# General Translation Knowledge Base: Come si migra da vue-i18n a gt-vue?
URL: https://generaltranslation.com/it/kb/migrate-from-vue-i18n.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Installa gt-vue accanto a vue-i18n, sincronizza l'impostazione regionale attiva e sposta un componente alla volta dalle chiavi $t al testo inline in `<T>` e useGT. General Translation traduce il testo spostato usando come contesto la struttura del template, e il tuo team può correggerlo nella Dashboard. I componenti non ancora migrati mantengono i messaggi vue-i18n già revisionati.
Category: Internazionalizzazione
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

vue-i18n renderizza le traduzioni che scrivi in un file di messaggi per ciascuna lingua. gt-vue renderizza invece il testo scritto inline nei tuoi template, mentre General Translation genera le traduzioni con [`npx gt translate`](/docs/cli/reference/commands/translate). Migrare significa sostituire ogni ricerca `$t('key')` con il testo di origine a cui fa riferimento, un componente alla volta, mentre entrambi i plugin restano attivi nella stessa app.

## Qual è la corrispondenza tra le API di vue-i18n e quelle di gt-vue?

| vue-i18n                                           | gt-vue                                                                                                                                                                                         |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createI18n({ locale, fallbackLocale, messages })` | [`createGT`](/docs/vue/reference/functions/create-gt)`({ defaultLocale, loadTranslations })`, con le impostazioni regionali in `gt.config.json`                                                |
| `app.use(i18n)`                                    | `app.use(gt)`                                                                                                                                                                                  |
| `$t('key')` nei template                           | [`<T>`](/docs/vue/reference/components/t) attorno al testo, oppure una stringa da [`useGT`](/docs/vue/reference/composables/use-gt)                                                            |
| `t('key')` in `<script setup>`                     | `const gt = useGT()`, poi `gt('Inbox')` all&#39;interno di un `computed`                                                                                                                       |
| Interpolazione con nome `{name}`                   | [`<Var>`](/docs/vue/reference/components/var) all&#39;interno di [`<T>`](/docs/vue/reference/components/t)                                                                                     |
| `<i18n-t keypath="...">` con slot                  | [`<T>`](/docs/vue/reference/components/t) che racchiude il markup effettivo                                                                                                                    |
| `'no apples \| one apple \| {count} apples'`       | [`<Plural>`](/docs/vue/reference/components/plural) con gli slot `#zero`, `#singular` e `#plural`                                                                                              |
| `n()` e `d()` con formati con nome                 | [`<Num>`](/docs/vue/reference/components/num), [`<Currency>`](/docs/vue/reference/components/currency) e [`<DateTime>`](/docs/vue/reference/components/datetime), con le opzioni `Intl` inline |
| `locale.value = 'fr'`                              | [`useSetLocale`](/docs/vue/reference/composables/use-set-locale)`()('fr')`; per leggerla, usa [`useLocale`](/docs/vue/reference/composables/use-locale)                                        |
| Caricamento lazy con `setLocaleMessage`            | L&#39;opzione `loadTranslations(locale)` carica e memorizza nella cache ogni impostazione regionale                                                                                            |
| `fallbackLocale`                                   | `defaultLocale`; se manca una traduzione, viene renderizzato il testo di origine                                                                                                               |

Le chiavi dei messaggi, i blocchi personalizzati `<i18n>` degli SFC e i messaggi collegati (`@:key`) diventano tutti testo inline: sposta il testo di ogni messaggio nel template che lo renderizza e scrivi per esteso i messaggi collegati.

## Passaggio 1: installa gt-vue insieme a vue-i18n

gt-vue (attualmente 0.x) supporta Vue 3.3 e versioni successive. Segui l&#39;[Avvio rapido di Vue](/docs/vue/quickstart). In sintesi:

1. Installa `gt-vue` e la CLI `gt` come dipendenza di sviluppo.

2. Crea `gt.config.json` con lo stesso locale di origine e le stesse impostazioni locali di destinazione della config di vue-i18n, oltre a un percorso di output come `src/_gt/[locale].json`.

3. Aggiungi una funzione `loadTranslations` e installa il plugin accanto a 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'; // la tua istanza createI18n esistente

   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. Accedi con [`npx gt login`](/docs/cli/reference/commands/login) e imposta l&#39;ID progetto.

gt-vue non richiede alcun plugin Vite: quando esegui [`npx gt translate`](/docs/cli/reference/commands/translate), la CLI analizza i file `.vue` alla ricerca di [`<T>`](/docs/vue/reference/components/t) e [`useGT`](/docs/vue/reference/composables/use-gt).

## Passaggio 2: Mantenere un solo locale attivo

Usa gt-vue come selettore della lingua e copia la sua impostazione regionale in vue-i18n, così anche i componenti non ancora migrati si adegueranno:

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

Sostituisci il menu delle lingue con un controllo che chiama [`useSetLocale`](/docs/vue/reference/composables/use-set-locale). Con [`createGT`](/docs/vue/reference/functions/create-gt), il cambio di lingua carica le traduzioni della nuova impostazione regionale e renderizza di nuovo l&#39;interfaccia senza ricaricare la pagina, mentre gt-vue salva la scelta nel cookie `generaltranslation.locale`.

## Passaggio 3: Migra un componente alla volta

Copia il testo in lingua sorgente dal file dei messaggi nel template. Prima:

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

Dopo:

```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 lo mantiene reattivo ai cambi dell'impostazione regionale
</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>
```

A partire dagli slot `singular` e `plural`, General Translation genera le forme richieste da ciascuna lingua di destinazione, come `few` e `many` del russo, e [`<Plural>`](/docs/vue/reference/components/plural) sceglie quella corretta tramite `Intl.PluralRules`; con la sintassi a pipe di vue-i18n, invece, per queste lingue serve una regola di pluralizzazione personalizzata. Lo slot `zero` conserva il testo che hai scritto per la casella di posta vuota. Usa [`useGT`](/docs/vue/reference/composables/use-gt) per le stringhe statiche, come titoli e segnaposto, e racchiudi in [`<T>`](/docs/vue/reference/components/t) con [`<Var>`](/docs/vue/reference/components/var) ogni frase che contiene un valore di runtime. Dopo ogni batch di componenti, esegui [`npx gt translate`](/docs/cli/reference/commands/translate) e verifica tutte le impostazioni regionali.

## Cosa succede alle traduzioni esistenti?

I componenti che non hai ancora migrato continuano a renderizzare i messaggi vue-i18n già revisionati, quindi una migrazione graduale interessa solo le schermate su cui intervieni. gt-vue identifica le traduzioni in base al contenuto di origine anziché alla chiave del messaggio: i testi che sposti in [`<T>`](/docs/vue/reference/components/t) o [`useGT`](/docs/vue/reference/composables/use-gt) ricevono nuove traduzioni da [`npx gt translate`](/docs/cli/reference/commands/translate), generate usando il template circostante come contesto. Il Glossario e i Prompt Personalizzati di un [gruppo di contesto](/docs/platform/dashboard/guides/defining-context-for-translations) mantengono coerenti terminologia e tono. I revisori possono poi correggere qualsiasi formulazione nella [dashboard](/docs/platform/dashboard/guides/reviewing-translations).

## Passaggio 4: rimuovi vue-i18n

Quando una ricerca di `$t(`, `useI18n`, `<i18n-t` e `vue-i18n` non restituisce più alcun risultato, rimuovi la configurazione di `createI18n`, i file dei messaggi, la sincronizzazione dell&#39;impostazione regionale e la dipendenza `vue-i18n`. Poi aggiungi [`npx gt translate`](/docs/cli/reference/commands/translate) alla build o alla [CI](/kb/translations-in-ci), così i nuovi testi verranno distribuiti già tradotti a ogni rilascio.

## Domande frequenti

### gt-vue supporta Nuxt?

gt-vue non dispone di un modulo Nuxt e, a differenza di `@nuxtjs/i18n`, non fornisce route localizzate, tag hreflang né rilevamento della lingua del browser. La CLI analizza comunque le cartelle `pages/` e `layouts/` di Nuxt e [`createGT`](/docs/vue/reference/functions/create-gt) può renderizzare sul server se crei un plugin per ogni richiesta.

### gt-vue supporta le chiavi dei messaggi?

No. gt-vue traduce i testi scritti inline in [`<T>`](/docs/vue/reference/components/t) e [`useGT`](/docs/vue/reference/composables/use-gt). Se le chiavi sono fondamentali per il tuo flusso di lavoro, continua a usare vue-i18n.

### Posso migrare un componente alla volta?

Sì. Entrambi i plugin possono coesistere nella stessa app, purché condividano il locale attivo. Rimuovi vue-i18n quando non ci sono più componenti che lo utilizzano.

### gt-vue è gratuito?

gt-vue è distribuito con licenza MIT e renderizza le traduzioni incluse nel bundle senza bisogno di un account. La generazione delle traduzioni con General Translation è invece [a consumo](https://generaltranslation.com/pricing).

## Punti chiave

* Usa gt-vue insieme a vue-i18n, cambia lingua con gt-vue e sincronizza la sua impostazione regionale in vue-i18n fino al termine della migrazione.
* Sostituisci le chiavi `$t` con testo inline: [`<T>`](/docs/vue/reference/components/t) con [`<Var>`](/docs/vue/reference/components/var) nei template, gli slot `singular` e `plural` di [`<Plural>`](/docs/vue/reference/components/plural) per i plurali con pipe e [`useGT`](/docs/vue/reference/composables/use-gt) all&#39;interno di un `computed` per le stringhe statiche negli script.
* I componenti non ancora migrati conservano i messaggi vue-i18n già revisionati; il testo migrato viene tradotto usando il relativo template come contesto e revisionato nella Dashboard. Mantieni vue-i18n se le chiavi dei messaggi o il routing di `@nuxtjs/i18n` sono fondamentali per la tua app.
* Rimuovi vue-i18n quando non viene più utilizzato da nessuna parte, quindi esegui [`npx gt translate`](/docs/cli/reference/commands/translate) nella CI.

## Related questions

- [General Translation vs. vue-i18n: quale scegliere?](https://generaltranslation.com/it/kb/general-translation-vs-vue-i18n.mdx): General Translation consente ai team Vue di scrivere il testo sorgente direttamente nei modelli e di generare le traduzioni con la CLI. Il suo plugin gt-vue renderizza questi contenuti con una formattazione locale-aware di plurali e numeri. Sceglilo per eliminare la manutenzione dei file sorgente basati su chiavi; vue-i18n resta una scelta valida per i team che usano il modulo i18n di Nuxt e un flusso di lavoro consolidato basato su cataloghi.
- [Come si traduce un'app Vue?](https://generaltranslation.com/it/kb/translate-vue-app.mdx): Tradurre un'app Vue significa far passare ogni stringa del template attraverso una ricerca nella lingua attiva e tradurla in ogni lingua di destinazione. Il plugin gt-vue di General Translation traduce il contenuto racchiuso nel componente `<T>` e npx gt translate genera un catalogo per ogni lingua di destinazione.
- [Come mantengo le traduzioni aggiornate a ogni distribuzione?](https://generaltranslation.com/it/kb/translations-in-ci.mdx): Esegui la traduzione come passaggio della pipeline prima di ogni build di produzione, così i nuovi testi vengono rilasciati già tradotti insieme alla distribuzione che li introduce. La CLI gt di General Translation lo fa con npx gt translate, usando una chiave API e un ID progetto archiviati come segreti CI.

## Previous and next questions

- Previous question: [Come si migra da react-i18next a gt-react?](https://generaltranslation.com/it/kb/migrate-from-react-i18next.mdx)
- Next question: [Agente di programmazione IA o pipeline di traduzione: a chi affidare l'automazione della localizzazione?](https://generaltranslation.com/it/kb/ai-coding-agent-vs-translation-pipeline.mdx)

## Sitemap

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