# General Translation Knowledge Base: ¿Cómo migro de vue-i18n a gt-vue?
URL: https://generaltranslation.com/es/kb/migrate-from-vue-i18n.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Instala gt-vue junto a vue-i18n, sincroniza la configuración regional activa y migra componente por componente de claves $t a texto inline en `<T>` y useGT. General Translation traduce el texto migrado usando la estructura de su plantilla como contexto, y tu equipo puede corregirlo en el panel de control. Los componentes que aún no se han migrado conservan sus mensajes de vue-i18n ya revisados.
Category: Internacionalización
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

vue-i18n renderiza las traducciones que escribes en un archivo de mensajes para cada idioma. gt-vue renderiza el texto escrito inline en tus plantillas, y General Translation genera las traducciones con [`npx gt translate`](/docs/cli/reference/commands/translate). Una migración reemplaza cada búsqueda `$t('key')` por el texto de origen al que hace referencia, componente por componente, mientras ambos plugins se ejecutan en la misma aplicación.

## ¿Cómo se corresponden las API de vue-i18n con gt-vue?

| vue-i18n                                           | gt-vue                                                                                                                                                                                              |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createI18n({ locale, fallbackLocale, messages })` | [`createGT`](/docs/vue/reference/functions/create-gt)`({ defaultLocale, loadTranslations })`, con las configuraciones regionales en `gt.config.json`                                                |
| `app.use(i18n)`                                    | `app.use(gt)`                                                                                                                                                                                       |
| `$t('key')` en plantillas                          | [`<T>`](/docs/vue/reference/components/t) alrededor del texto, o una cadena obtenida de [`useGT`](/docs/vue/reference/composables/use-gt)                                                           |
| `t('key')` en `<script setup>`                     | `const gt = useGT()` y, después, `gt('Inbox')` dentro de un `computed`                                                                                                                              |
| Interpolación con nombre `{name}`                  | [`<Var>`](/docs/vue/reference/components/var) dentro de [`<T>`](/docs/vue/reference/components/t)                                                                                                   |
| `<i18n-t keypath="...">` con slots                 | [`<T>`](/docs/vue/reference/components/t) envolviendo el marcado real                                                                                                                               |
| `'no apples \| one apple \| {count} apples'`       | [`<Plural>`](/docs/vue/reference/components/plural) con los slots `#zero`, `#singular` y `#plural`                                                                                                  |
| `n()` y `d()` con formatos con nombre              | [`<Num>`](/docs/vue/reference/components/num), [`<Currency>`](/docs/vue/reference/components/currency) y [`<DateTime>`](/docs/vue/reference/components/datetime), con las opciones de `Intl` inline |
| `locale.value = 'fr'`                              | [`useSetLocale`](/docs/vue/reference/composables/use-set-locale)`()('fr')`; para leerla, usa [`useLocale`](/docs/vue/reference/composables/use-locale)                                              |
| Carga diferida con `setLocaleMessage`              | La opción `loadTranslations(locale)` carga cada configuración regional y la almacena en caché                                                                                                       |
| `fallbackLocale`                                   | `defaultLocale`; si falta una traducción, se renderiza el texto de origen                                                                                                                           |

Las claves de mensajes, los bloques personalizados `<i18n>` de SFC y los mensajes enlazados (`@:key`) se convierten en texto inline: mueve el texto de cada mensaje a la plantilla que lo renderiza y escribe los mensajes enlazados completos.

## Paso 1: Instala gt-vue junto a vue-i18n

gt-vue (actualmente en versión 0.x) es compatible con Vue 3.3 y versiones posteriores. Sigue el [Inicio rápido de Vue](/docs/vue/quickstart). En resumen:

1. Instala `gt-vue` y la CLI `gt` como dependencia de desarrollo.

2. Crea `gt.config.json` con la misma configuración regional de origen y las mismas configuraciones regionales de destino que en tu configuración de vue-i18n, además de una ruta de salida como `src/_gt/[locale].json`.

3. Agrega una función `loadTranslations` e instala el plugin junto 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'; // tu instancia existente de createI18n

   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. Inicia sesión con [`npx gt login`](/docs/cli/reference/commands/login) y configura el ID del proyecto.

gt-vue no necesita ningún plugin de Vite: la CLI analiza los archivos `.vue` en busca de [`<T>`](/docs/vue/reference/components/t) y [`useGT`](/docs/vue/reference/composables/use-gt) al ejecutar [`npx gt translate`](/docs/cli/reference/commands/translate).

## Paso 2: Mantén una sola configuración regional activa

Usa gt-vue como selector de idioma y copia su configuración regional en vue-i18n para que los componentes que aún no has migrado también la sigan:

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

Sustituye tu menú de idiomas por un control que llame a [`useSetLocale`](/docs/vue/reference/composables/use-set-locale). Con [`createGT`](/docs/vue/reference/functions/create-gt), al cambiar de idioma se cargan las traducciones de la nueva configuración regional y la interfaz se vuelve a renderizar sin recargar la página. Además, gt-vue guarda la selección en la cookie `generaltranslation.locale`.

## Paso 3: Migra los componentes de uno en uno

Copia el texto en el idioma de origen de tu archivo de mensajes a la plantilla. Antes:

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

Despué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 hace que se actualice al cambiar la configuración regional
</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 partir de los slots `singular` y `plural`, General Translation genera las formas que necesita cada idioma de destino, como `few` y `many` en ruso, y [`<Plural>`](/docs/vue/reference/components/plural) elige la adecuada con `Intl.PluralRules`; en cambio, la sintaxis de barras verticales de vue-i18n requiere una regla de pluralización personalizada para esos idiomas. El slot `zero` conserva tu redacción para cuando la bandeja de entrada está vacía. Usa [`useGT`](/docs/vue/reference/composables/use-gt) para cadenas estáticas, como títulos y marcadores de posición, y coloca cualquier oración que contenga un valor en tiempo de ejecución dentro de [`<T>`](/docs/vue/reference/components/t) con [`<Var>`](/docs/vue/reference/components/var). Después de cada lote de componentes, ejecuta [`npx gt translate`](/docs/cli/reference/commands/translate) y revisa todas las configuraciones regionales.

## ¿Qué pasa con tus traducciones existentes?

Los componentes que aún no hayas migrado siguen renderizando sus mensajes de vue-i18n ya revisados, así que una migración gradual solo afecta a las pantallas que modifiques. gt-vue identifica las traducciones por su contenido de origen, no por la clave del mensaje, por lo que el texto que muevas a [`<T>`](/docs/vue/reference/components/t) o [`useGT`](/docs/vue/reference/composables/use-gt) recibe nuevas traducciones de [`npx gt translate`](/docs/cli/reference/commands/translate), generadas con la plantilla que lo rodea como contexto. El glosario y los prompts personalizados de un [grupo de contexto](/docs/platform/dashboard/guides/defining-context-for-translations) mantienen tu terminología y tu tono. Después, los revisores pueden corregir cualquier redacción en el [panel de control](/docs/platform/dashboard/guides/reviewing-translations).

## Paso 4: Eliminar vue-i18n

Cuando una búsqueda de `$t(`, `useI18n`, `<i18n-t` y `vue-i18n` ya no devuelva resultados, elimina la configuración inicial de `createI18n`, los archivos de mensajes, la sincronización de la configuración regional y la dependencia `vue-i18n`. Después, añade [`npx gt translate`](/docs/cli/reference/commands/translate) a tu proceso de compilación o a tu [CI](/kb/translations-in-ci) para que el contenido nuevo se publique ya traducido en cada lanzamiento.

## Preguntas frecuentes

### ¿gt-vue es compatible con Nuxt?

gt-vue no tiene un módulo para Nuxt ni ofrece rutas localizadas, etiquetas hreflang o detección de idioma del navegador como hace `@nuxtjs/i18n`. Aun así, la CLI sí analiza las carpetas `pages/` y `layouts/` de Nuxt, y [`createGT`](/docs/vue/reference/functions/create-gt) puede renderizar en el servidor si creas un plugin por cada solicitud.

### ¿gt-vue admite claves de mensaje?

No. gt-vue traduce el texto escrito inline en [`<T>`](/docs/vue/reference/components/t) y [`useGT`](/docs/vue/reference/composables/use-gt). Si las claves son esenciales en tu flujo de trabajo, sigue usando vue-i18n.

### ¿Puedo migrar los componentes de uno en uno?

Sí. Ambos plugins pueden ejecutarse en la misma aplicación siempre que compartan la configuración regional activa. Elimina vue-i18n cuando ya no quede ningún componente que lo utilice.

### ¿Es gratuito gt-vue?

gt-vue tiene licencia MIT y renderiza traducciones empaquetadas sin necesidad de una cuenta. La generación de traducciones con General Translation se [factura según el uso](https://generaltranslation.com/pricing).

## Puntos clave

* Ejecuta gt-vue junto a vue-i18n, cambia de idioma con gt-vue y copia su configuración regional en vue-i18n hasta que termine la migración.
* Sustituye las claves de `$t` por texto inline: [`<T>`](/docs/vue/reference/components/t) con [`<Var>`](/docs/vue/reference/components/var) en las plantillas, los slots `singular` y `plural` de [`<Plural>`](/docs/vue/reference/components/plural) para los plurales con barra vertical, y [`useGT`](/docs/vue/reference/composables/use-gt) dentro de un `computed` para las cadenas estáticas del script.
* Los componentes que aún no se hayan migrado conservan sus mensajes de vue-i18n ya revisados; el texto migrado se traduce con su plantilla como contexto y se revisa en el panel de control. Mantén vue-i18n si las claves de mensajes o el enrutamiento de `@nuxtjs/i18n` son fundamentales en tu aplicación.
* Elimina vue-i18n cuando ya nada lo utilice y, después, ejecuta [`npx gt translate`](/docs/cli/reference/commands/translate) en CI.

## Related questions

- [General Translation vs. vue-i18n: ¿cuál deberías usar?](https://generaltranslation.com/es/kb/general-translation-vs-vue-i18n.mdx): General Translation permite a los equipos de Vue escribir el texto de origen directamente en las plantillas y generar traducciones con la CLI. Su plugin gt-vue renderiza ese contenido con formato de plurales y de números adaptado a la configuración regional. Elígelo si quieres dejar de mantener archivos de origen basados en claves; vue-i18n sigue siendo una buena opción para equipos que usan el módulo i18n de Nuxt y un flujo de trabajo de catálogos ya consolidado.
- [¿Cómo traduzco una aplicación Vue?](https://generaltranslation.com/es/kb/translate-vue-app.mdx): Traducir una aplicación Vue implica que cada cadena de las plantillas se obtenga mediante una búsqueda según el idioma activo y se traduzca a cada idioma de destino. El plugin gt-vue de General Translation traduce el contenido envuelto en el componente `<T>`, y npx gt translate genera un catálogo por cada idioma de destino.
- [¿Cómo mantengo las traducciones actualizadas en cada despliegue?](https://generaltranslation.com/es/kb/translations-in-ci.mdx): Ejecuta la traducción como un paso del flujo antes de cada compilación de producción, para que el texto nuevo se publique ya traducido en el mismo despliegue que lo incorpora. La CLI gt de General Translation lo hace con npx gt translate, usando una clave de API del proyecto y el ID del proyecto almacenados como secretos de CI.

## Previous and next questions

- Previous question: [¿Cómo migro de react-i18next a gt-react?](https://generaltranslation.com/es/kb/migrate-from-react-i18next.mdx)
- Next question: [¿Cómo migro de Crowdin a General Translation?](https://generaltranslation.com/es/kb/migrate-from-crowdin.mdx)

## Sitemap

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