# General Translation Knowledge Base: ¿Cómo migro de react-i18next a gt-react?
URL: https://generaltranslation.com/es/kb/migrate-from-react-i18next.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Instala gt-react junto a react-i18next, comparte una única cookie de configuración regional y migra los componentes de uno en uno, pasando de claves t() y `<Trans>` a texto inline en `<T>` y useGT. General Translation traduce el texto migrado usando su JSX como contexto, y tu equipo puede corregirlo en el panel de control. Los componentes que aún no hayas migrado conservan sus traducciones revisadas de react-i18next.
Category: Internacionalización
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

react-i18next renderiza las traducciones que escribes en un archivo JSON por cada idioma y namespace. gt-react renderiza el texto escrito inline en tus componentes, y General Translation genera las traducciones con [`npx gt translate`](/docs/cli/reference/commands/translate). Durante la migración, se reemplaza cada búsqueda `t('key')` por el texto de origen al que apunta, componente a componente, mientras ambas bibliotecas conviven en paralelo.

No necesitas migrar para usar General Translation. La CLI `gt` detecta `i18next` en tu `package.json` y traduce sus archivos JSON sin alterar la sintaxis `{{variable}}` de i18next. Migra cuando quieras tener el texto junto al JSX que lo renderiza, sin tener que nombrar claves ni mantener sincronizados a mano los archivos de cada idioma.

## ¿Cómo se corresponden las API de react-i18next con gt-react?

| react-i18next                                  | gt-react                                                                                                                                                                                                                              |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `i18n.init({ lng, supportedLngs, resources })` | `gt.config.json` (`defaultLocale`, `locales`) e [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) en el archivo de entrada                                                                                             |
| `I18nextProvider` / `initReactI18next`         | No se necesita proveedor en una aplicación de una sola página (SPA); las aplicaciones server-rendered usan [`initializeGT`](/docs/react/reference/config#initialize) con [`GTProvider`](/docs/react/reference/components/gt-provider) |
| `<Trans i18nKey="..." components={...}>`       | [`<T>`](/docs/react/reference/components/t) envolviendo el JSX real, con los enlaces y el marcado escritos inline                                                                                                                     |
| `t('key')` para cadenas                        | [`useGT`](/docs/react/reference/hooks/use-gt) con la cadena de origen, o [`useTranslations`](/docs/react/reference/hooks/use-translations) para conservar las claves                                                                  |
| Interpolación `{{name}}`                       | [`<Var>`](/docs/react/reference/components/var) en JSX; `{name}` en cadenas                                                                                                                                                           |
| `key_one` / `key_other` con `count`            | [`<Plural>`](/docs/react/reference/components/plural) en JSX; ICU `{n, plural, ...}` en cadenas                                                                                                                                       |
| `useTranslation('ns')` o `keyPrefix`           | `useTranslations('ns')` limita las búsquedas a un prefijo                                                                                                                                                                             |
| `{{val, number}}` y otros formateadores        | [`<Num>`](/docs/react/reference/components/num), [`<Currency>`](/docs/react/reference/components/currency) y [`<DateTime>`](/docs/react/reference/components/datetime)                                                                |
| `i18n.changeLanguage()` / `i18n.language`      | [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) / [`useLocale`](/docs/react/reference/hooks/use-locale), o el componente [`<LocaleSelector>`](/docs/react/reference/components/locale-selector)                          |
| `i18next-browser-languagedetector`             | Integrado: primero la cookie `generaltranslation.locale` y, después, los idiomas del navegador                                                                                                                                        |
| `fallbackLng`                                  | Si falta una traducción, se renderiza el texto de origen                                                                                                                                                                              |

## Paso 1: Instala gt-react junto con react-i18next

Sigue la [Guía de inicio rápido para una SPA de React](/docs/react/react-spa-quickstart) si tu aplicación usa Vite o webpack, o el [Quickstart de React](/docs/react/react-quickstart) si es una aplicación server-rendered. En una SPA, la configuración inicial consiste en:

1. Instalar `gt-react` y la CLI `gt` como dependencia de desarrollo.
2. Crear `gt.config.json` con la misma configuración regional de origen y las mismas configuraciones regionales de destino que tu configuración de i18next.
3. Añadir una función [`loadTranslations`](/docs/react/reference/functions/load-translations) y llamar a [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) en un archivo de entrada que importe el resto de la aplicación solo después de que se carguen las traducciones.
4. Iniciar sesión con [`npx gt login`](/docs/cli/reference/commands/login) y configurar el ID del proyecto.

Conserva `i18n.init` y tus archivos JSON tal como están. Los usuarios no notarán ningún cambio hasta que migres un componente. Si `gt.config.json` incluye tus archivos de i18next en `files`, elimina esa entrada para que la traducción de cada cadena tenga un único responsable: los JSON conservan sus traducciones para los componentes sin migrar, y el texto nuevo o modificado se escribe inline en gt-react.

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

Dos bibliotecas pueden discrepar sobre el idioma del usuario. Usa gt-react como selector de idioma y haz que i18next lea la misma cookie:

```ts title="src/i18n.ts"
import i18n from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import { initReactI18next } from 'react-i18next';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    // ...tus opciones actuales
    detection: {
      order: ['cookie', 'navigator'],
      lookupCookie: 'generaltranslation.locale', // la cookie que guarda gt-react
      caches: [],
    },
  });
```

Sustituye tu antiguo menú de idiomas por el [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) de gt-react o por un control que llame a [`useSetLocale`](/docs/react/reference/hooks/use-set-locale). En una SPA, al cambiar de idioma se escribe la cookie y se recarga la página, de modo que ambas bibliotecas arrancan en el nuevo idioma. Antes de seguir, prueba la navegación entre las pantallas ya migradas y las que aún no lo están.

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

Copia en el componente el texto en el idioma de origen que tienes en tu JSON y conserva las variables como variables. Antes:

```json title="public/locales/en/translation.json"
{
  "inbox": "Hi {{name}}, <link>open your inbox</link>.",
  "messages_one": "You have {{count}} message",
  "messages_other": "You have {{count}} messages"
}
```

```tsx title="src/Inbox.tsx"
import { Trans, useTranslation } from 'react-i18next';

export function Inbox({ name, count }: { name: string; count: number }) {
  const { t } = useTranslation();
  return (
    <>
      <Trans i18nKey="inbox" values={{ name }} components={{ link: <a href="/inbox" /> }} />
      <p>{t('messages', { count })}</p>
    </>
  );
}
```

Después:

```tsx title="src/Inbox.tsx"
import { T, Var, Plural, Num } from 'gt-react';

export function Inbox({ name, count }: { name: string; count: number }) {
  return (
    <T>
      Hi <Var>{name}</Var>, <a href="/inbox">open your inbox</a>.
      <p>
        <Plural
          n={count}
          singular={<>You have <Num>{count}</Num> message</>}
          plural={<>You have <Num>{count}</Num> messages</>}
        />
      </p>
    </T>
  );
}
```

El enlace sigue siendo un elemento `<a>` real en lugar de un marcador de posición numerado. General Translation traduce todo el bloque usando su estructura como contexto y, a partir de las formas `singular` y `plural` que escribas, genera las formas que necesita cada idioma de destino, como las formas `few` y `many` del polaco. Después, [`<Plural>`](/docs/react/reference/components/plural) elige la adecuada para cada cantidad.

Para las cadenas fuera de JSX, como los textos de ejemplo de los campos y las notificaciones emergentes (toasts), usa [`useGT`](/docs/react/reference/hooks/use-gt). Las variables se escriben entre llaves simples y puedes añadir contexto para las palabras ambiguas:

```tsx
import { useGT } from 'gt-react';

function Search({ count }: { count: number }) {
  const gt = useGT();
  return <input placeholder={gt('Search {count} projects', { count })} />;
}

// En un controlador de eventos, con una pista para el traductor:
toast(gt('Saved {fileName}', { fileName, $context: 'toast after saving a file' }));
```

El primer argumento debe ser una cadena estática, no un literal de plantilla ni una concatenación. Después de cada lote de componentes, ejecuta [`npx gt translate`](/docs/cli/reference/commands/translate) y revisa todas las configuraciones regionales.

## ¿Puedes conservar tus claves de traducción?

Sí. Traslada tus claves a un único [diccionario](/docs/react/guides/translating-with-dictionaries) de gt-react y reemplaza `useTranslation` por [`useTranslations`](/docs/react/reference/hooks/use-translations). La llamada de búsqueda no cambia:

```tsx
// Antes
import { useTranslation } from 'react-i18next';
const { t } = useTranslation();

// Después
import { useTranslations } from 'gt-react';
const t = useTranslations();

return <h1>{t('home.welcome', { name })}</h1>;
```

Las entradas del diccionario usan el formato de mensajes ICU, así que el JSON necesita tres cambios:

* `{{name}}` pasa a ser `{name}`.
* Las claves de plural se combinan en una sola entrada: `"messages": "You have {count, plural, one {# message} other {# messages}}"`.
* Los archivos de cada namespace se combinan en un único `dictionary.json`, donde cada namespace es una clave de nivel superior. `useTranslation('settings')` pasa a ser `useTranslations('settings')`.

[`npx gt validate`](/docs/cli/reference/commands/validate) avisa de las entradas que no son ICU válido. A diferencia de i18next, que devuelve la clave cuando falta una entrada, [`useTranslations`](/docs/react/reference/hooks/use-translations) lanza un error, así que mantén sincronizados los ids y las entradas.

## ¿Qué pasa con tus traducciones existentes?

Los componentes que no hayas migrado siguen renderizando sus traducciones revisadas de react-i18next, así que una migración gradual solo afecta a las pantallas que toques. El texto que pases a [`<T>`](/docs/react/reference/components/t), [`useGT`](/docs/react/reference/hooks/use-gt) o a un diccionario de gt-react recibe nuevas traducciones con [`npx gt translate`](/docs/cli/reference/commands/translate), que tienen en cuenta la estructura JSX de [`<T>`](/docs/react/reference/components/t) y cualquier contexto que añadas. 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 texto en el [panel de control](/docs/platform/dashboard/guides/reviewing-translations).

Si todas las traducciones revisadas deben quedarse exactamente como están, mantén react-i18next y deja que General Translation traduzca sus archivos JSON. (Consulta [General Translation vs. i18next](/kb/general-translation-vs-i18next)).

## Paso 4: Eliminar react-i18next

Cuando al buscar `useTranslation`, `<Trans` e `i18next` no obtengas ningún resultado, elimina el archivo `i18n.init`, los archivos JSON, el detector de idioma y las dependencias `i18next` y `react-i18next`. 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 salga traducido en cada lanzamiento.

## Preguntas frecuentes

### ¿Tengo que migrar todo de una vez?

No. Ambas bibliotecas pueden renderizar en la misma página siempre que lean la misma configuración regional. Migra una ruta o funcionalidad cada vez y elimina i18next cuando ya no quede nada que lo use.

### ¿gt-react admite el renderizado server-side?

Sí. Las aplicaciones React renderizadas en el servidor usan [`initializeGT`](/docs/react/reference/config#initialize) con [`GTProvider`](/docs/react/reference/components/gt-provider) en lugar de [`initializeGTSPA`](/docs/react/reference/config#initialize-spa). Consulta el [Quickstart de React](/docs/react/react-quickstart) o, si usas `gt-next`, el [Inicio rápido de Next.js](/docs/react/nextjs-quickstart).

### ¿Es gratuito gt-react?

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

## Conclusiones clave

* Ejecuta gt-react junto a react-i18next, configura el detector de idioma de i18next para que lea la cookie `generaltranslation.locale` y cambia de idioma con gt-react.
* Sustituye `<Trans>` y las búsquedas por clave por texto inline en [`<T>`](/docs/react/reference/components/t) y [`useGT`](/docs/react/reference/hooks/use-gt); `{{var}}` pasa a ser [`<Var>`](/docs/react/reference/components/var) o `{var}`, y las claves de plural pasan a ser [`<Plural>`](/docs/react/reference/components/plural) con `singular` y `plural`.
* Los componentes que no se migran conservan sus traducciones revisadas; el texto migrado se traduce usando su JSX como contexto y se revisa en el panel de control.
* Para conservar las claves, convierte tu JSON en un único diccionario ICU y usa [`useTranslations`](/docs/react/reference/hooks/use-translations).
* Elimina i18next solo cuando ya nada lo lea y, después, ejecuta [`npx gt translate`](/docs/cli/reference/commands/translate) en CI.

## Related questions

- [Alternativas a i18next: General Translation vs. i18next](https://generaltranslation.com/es/kb/general-translation-vs-i18next.mdx): Elige General Translation para mantener los textos inline en los componentes de React y generar traducciones a partir de su estructura JSX y del contexto del producto. También puedes seguir usando i18next y recurrir a General Translation para traducir los catálogos existentes. i18next se encarga de renderizar los mensajes y seleccionar los plurales, pero las traducciones las genera un servicio aparte.
- [¿Cómo traduzco una aplicación de React?](https://generaltranslation.com/es/kb/translate-react-app.mdx): Traducir una aplicación de React significa internacionalizar sus componentes para que se rendericen en el idioma del usuario y, después, traducir cada cadena a todos los idiomas que admitas. gt-react de General Translation traduce JSX en el mismo documento con el componente `<T>`, y npx gt translate genera un archivo por idioma.
- [¿Cómo traduzco cadenas fuera de JSX?](https://generaltranslation.com/es/kb/translate-strings-outside-jsx.mdx): Pasa cada cadena que no sea un hijo de JSX, como un marcador de posición o una constante en el ámbito del módulo, por una función de traducción en el lugar donde se renderiza. El hook useGT de General Translation devuelve esa función, y msg junto con useMessages traduce las constantes definidas fuera de un componente.
- [¿Cómo gestiono los plurales en React?](https://generaltranslation.com/es/kb/how-to-handle-plurals-in-react.mdx): Para gestionar los plurales en React, asigna a cada idioma una oración por cada forma plural y selecciónala con las reglas de plural de ese idioma, ya que el inglés tiene 2 formas, el ruso tiene 4 y el árabe tiene 6. El componente `<Plural>` de General Translation en gt-react y gt-next recibe tus formas de origen, y General Translation genera las formas que necesita 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 next-intl a gt-next?](https://generaltranslation.com/es/kb/migrate-from-next-intl.mdx)
- Next question: [¿Cómo migro de vue-i18n a gt-vue?](https://generaltranslation.com/es/kb/migrate-from-vue-i18n.mdx)

## Sitemap

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