Migración
Aprende a migrar un proyecto a gt-next
Descripción general
Esta guía explica los pasos necesarios para migrar un proyecto que ya utiliza una biblioteca de i18n a gt-next.
También compartiremos consejos y recomendaciones para que la migración sea lo más fluida posible.
Requisitos previos
- Un proyecto que actualmente utilice otra biblioteca de i18n.
- Un conocimiento básico de la biblioteca
gt-next.
¿Por qué migrar?
Hay muchas razones por las que podrías querer migrar tu proyecto a gt-next.
Aquí tienes solo algunas:
- No más archivos JSON: Nunca vuelvas a gestionar traducciones en archivos JSON. Todo tu contenido vive junto a tu código, donde corresponde.
- Traducciones automáticas: Genera traducciones de alta calidad y con reconocimiento de contexto con nuestra herramienta CLI. Nunca más tendrás que esperar las traducciones.
- Experimenta en desarrollo: Prueba fácilmente con traducciones en desarrollo con recarga en caliente de traducciones.
Configuración
Instala gt-next y la CLI gtx-cli.
npm i gt-next gtx-cliyarn add gt-next
yarn add --dev gtx-clibun add gt-next
bun add --dev gtx-clipnpm add gt-next
pnpm add --save-dev gtx-cliCrea un archivo gt.config.json en la raíz de tu proyecto que contenga la propiedad defaultLocale y un array locales.
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}Luego, añade el componente <GTProvider> al layout raíz de tu aplicación.
import { GTProvider } from 'gt-next'
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
)
}A continuación, añade withGTConfig a tu archivo next.config.js.
import withGTConfig from 'gt-next/config'
const nextConfig = {
// Your next.config.ts options
}
export default withGTConfig(nextConfig, {
// Your GT configuration
})Para ver pasos más detallados, consulta la guía de inicio rápido.
En este punto, tienes 3 opciones:
- Migrar por completo todo tu proyecto a
gt-nexty eliminar la biblioteca de i18n anterior. - Migrar completamente tu proyecto, pero seguir usando diccionarios de la biblioteca de i18n anterior.
- Seguir usando por ahora la biblioteca de i18n anterior y migrar solo una parte de tu proyecto a
gt-next.
Para más detalles sobre cada opción, consulta la sección de estrategias de migración.
Estrategias de migración
Opción 1: Migrar por completo todo tu proyecto
Esta opción es la más directa y también requerirá la mayor cantidad de cambios de código de una sola vez.
Después de configurar tu proyecto, tendrás que buscar todas las instancias de tu antigua biblioteca de i18n y reemplazarlas por gt-next.
Si tu app usa hooks de React como useTranslations, busca todas las instancias de useTranslations en tu base de código y cámbialas por useGT.
Luego tendrás que sustituir todas las claves de texto por sus valores de texto reales.
Por ejemplo, si tu código anterior se ve así:
{
"hello": {
"description": "¡Hola, mundo!"
}
}export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}Deberás reemplazarlo con:
export default function MyComponent() {
const t = useGT()
return <div>{t('¡Hola, mundo!')}</div>
}
// O
export default function MyComponent() {
return <T>¡Hola, mundo!</T>
}Haz esto en todas las instancias de tu biblioteca de i18n anterior.
Opción 2: Migra completamente tu proyecto, pero sigue usando diccionarios de la biblioteca i18n anterior
Supongamos que quieres migrar tu proyecto a gt-next, pero quieres seguir usando diccionarios de la biblioteca i18n anterior y usar las funciones en línea de GT solo para el contenido nuevo.
En este caso, puedes hacer algo similar a la Opción 1:
Localiza todas las instancias de tu biblioteca i18n anterior, como los hooks useTranslations, y reemplázalas por los hooks useTranslations de gt-next.
El hook useTranslations se comporta de forma muy similar a los hooks useTranslations en otras bibliotecas de i18n, y puedes usarlo del mismo modo.
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}import { useTranslations } from 'gt-next'
export default function MyComponent() {
const t = useTranslations()
return <div>{t('hello.description')}</div>
}En cuanto a la configuración, deberás crear un archivo dictionary.[js|ts|json] en la raíz de tu proyecto o en el directorio src.
Copia el contenido de tu antiguo archivo de diccionario en este nuevo archivo.
La función de inicialización withGTConfig en next.config.js detectará automáticamente el archivo de diccionario en la raíz de tu proyecto o en el directorio src.
Consulta la guía de diccionarios para más detalles.
Opción 3: Sigue usando por ahora la biblioteca de i18n anterior y migra solo parte de tu proyecto a gt-next
Esta opción es la más flexible y requerirá la menor cantidad de cambios de código de una sola vez.
En este caso, puedes hacer algo parecido a la Opción 2, pero migrando solo una parte de tu proyecto a gt-next.
Por ejemplo, puedes seguir usando la biblioteca de i18n anterior en algunos componentes y usar gt-next únicamente en otros y para contenido nuevo.
Esta opción no es recomendable, ya que tendrás que gestionar dos bibliotecas de i18n en tu proyecto, lo que puede ser complejo y provocar errores.
Recomendaciones para la migración
1. Usa el hook useGT o el componente <T> tanto como sea posible
Siempre que sea posible, te recomendamos usar el hook useGT o el componente <T>.
Esto facilitará mucho la edición de tu contenido en el futuro y hará que tu base de código sea mucho más legible.
2. Usa el hook useTranslations para contenido existente
El hook useTranslations es una excelente manera de seguir utilizando tus dictionaries existentes.
Lo ofrecemos para facilitar la migración, pero no recomendamos usarlo para contenido nuevo.
3. Uso de IA
Si estás usando IA para ayudarte a migrar tu proyecto, ponemos a tu disposición LLMs.txt y LLMs-full.txt en:
¿Qué te parece esta guía?