Migración
Aprende a migrar un proyecto a gt-next
Descripción general
Esta guía describe los pasos necesarios para migrar un proyecto que ya utiliza una biblioteca de i18n a gt-next.
También compartiremos algunos consejos y recomendaciones para que la migración sea lo más fluida posible.
Requisitos previos
- Un proyecto que actualmente use otra biblioteca de i18n.
- Conocimientos básicos de la biblioteca
gt-next.
¿Por qué migrar?
Hay muchas razones por las que quizá quieras migrar tu proyecto a gt-next.
Aquí tienes solo algunas:
- Adiós a los archivos JSON: No vuelvas a gestionar traducciones en archivos JSON. Todo tu contenido vive junto a tu código, donde debe estar.
- Traducciones automáticas: Genera traducciones de alta calidad y con contexto con nuestra herramienta CLI. Nunca más tendrás que esperar por traducciones.
- Prueba en desarrollo: Experimenta fácilmente con traducciones en desarrollo con recarga en caliente.
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 incluya la propiedad defaultLocale y el arreglo locales.
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}Luego, agrega el componente <GTProvider> al layout raíz de tu app.
import { GTProvider } from 'gt-next'
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
)
}A continuación, agrega 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 pasos más detallados, consulta la guía de inicio rápido.
En este punto, tienes 3 opciones:
- Migrar por completo tu proyecto a
gt-nexty eliminar la biblioteca de i18n anterior. - Migrar por completo tu proyecto, pero seguir usando los dictionaries de la biblioteca de i18n anterior.
- Seguir usando la biblioteca de i18n anterior por ahora y migrar solo 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 completamente 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, deberás buscar todas las instancias de tu antigua biblioteca de i18n y reemplazarlas por gt-next.
Si tu app está usando hooks de React como useTranslations, busca todas las instancias de useTranslations en tu base de código y reemplázalas por useGT.
Luego, tendrás que reemplazar todas las claves de cadena por sus valores de cadena reales.
Por ejemplo, si tu código anterior luce así:
{
"hello": {
"description": "¡Hola, mundo!"
}
}export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}Deberás reemplazarlo por:
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 por completo tu proyecto, pero sigue usando los diccionarios de la biblioteca i18n anterior
Supongamos que quieres migrar tu proyecto a gt-next, pero deseas seguir usando los diccionarios de la biblioteca i18n anterior y utilizar las funciones en línea de GT solo para el contenido nuevo.
En este caso, puedes hacer algo similar a la Opción 1:
Busca todas las instancias de tu biblioteca i18n anterior, como los hooks useTranslations, y sustitúyelas por los hooks useTranslations de gt-next.
El hook useTranslations se comporta de forma muy similar a los hooks useTranslations de 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, necesitará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 archivo de diccionario anterior 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 dictionaries para más detalles.
Opción 3: Mantén 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 requiere realizar menos cambios de código de una sola vez.
En este caso, puedes hacer algo similar a la Opción 2, pero migrar únicamente parte de tu proyecto a gt-next.
Por ejemplo, puedes seguir usando la biblioteca de i18n anterior para algunos componentes y usar gt-next solo para otros y para contenido nuevo.
Esta opción no es recomendable, ya que tendrás que gestionar dos bibliotecas de i18n en el mismo proyecto, lo que puede ser complejo y causar errores.
Consejos para la migración
1. Usa el hook useGT o el componente <T> tanto como sea posible
Siempre que sea posible, recomendamos usar el hook useGT o el componente <T>.
Esto hará que editar tu contenido en el futuro sea mucho más fácil y 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 usando tus dictionaries existentes.
Lo ofrecemos para facilitar la migración, pero no recomendamos usarlo para contenido nuevo.
3. Uso de IA
Si utilizas IA para ayudarte a migrar tu proyecto, contamos con LLMs.txt y LLMs-full.txt disponibles en:
¿Qué te ha parecido esta guía?