Migración
Aprende cómo migrar un proyecto a gt-next
Descripción general
Esta guía cubrirá los pasos necesarios para migrar un proyecto que ya está utilizando una biblioteca i18n a gt-next.
También proporcionaremos algunos consejos y sugerencias para que la migración sea lo más fluida posible.
Requisitos previos
- Un proyecto que actualmente esté utilizando otra biblioteca de i18n.
- Una comprensión básica 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 algunas:
- No más archivos JSON: Nunca más gestiones traducciones en archivos JSON. Todo tu contenido vive en línea con tu código, donde debe estar.
- Traducciones automáticas: Genera traducciones de alta calidad y con contexto usando nuestra herramienta CLI. Nunca más tendrás que esperar por traducciones.
- Experimenta en desarrollo: Experimenta fácilmente con traducciones en desarrollo gracias a la recarga en caliente de traducciones.
Configuración
Instala gt-next y la herramienta CLI gtx-cli.
npm i gt-next
npm i --save-dev 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 una propiedad defaultLocale y un array locales.
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}Luego, agrega 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, 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 completamente todo tu proyecto a
gt-next, y eliminar la antigua biblioteca i18n. - Migrar completamente tu proyecto, pero seguir usando diccionarios de la antigua biblioteca i18n.
- Seguir usando la antigua biblioteca i18n por ahora, y solo migrar 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, necesitarás buscar todas las instancias de tu antigua biblioteca i18n y reemplazarlas con gt-next.
Si tu aplicación está usando React hooks como useTranslations, busca todas las instancias de useTranslations en tu código base y reemplázalas con useGT.
Luego, necesitarás reemplazar todas las claves de cadena con sus valores de cadena reales.
Por ejemplo, si tu código anterior se ve así:
{
"hello": {
"description": "Hello, world!"
}
}export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}Necesitarás reemplazarlo con:
export default function MyComponent() {
const t = useGT()
return <div>{t('Hello, world!')}</div>
}
// OR
export default function MyComponent() {
return <T>Hello, world!</T>
}Haz esto para todas las instancias de tu antigua biblioteca i18n.
Opción 2: Migrar completamente tu proyecto, pero seguir usando diccionarios de la antigua biblioteca i18n
Digamos que quieres migrar tu proyecto a gt-next, pero quieres seguir usando diccionarios de la antigua biblioteca i18n
y solo usar las características en línea de GT para contenido nuevo.
En este caso, puedes hacer algo similar a la Opción 1:
Encuentra todas las instancias de tu antigua biblioteca i18n, como hooks useTranslations, y reemplázalas con hooks useTranslations de gt-next.
El hook useTranslations se comporta de manera muy similar a los hooks useTranslations en otras bibliotecas i18n, y puedes usarlo de la misma manera.
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 términos de configuración, necesitarás crear un archivo dictionary.[js|ts|json] en la raíz de tu proyecto o 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 automáticamente detectará el archivo de diccionario en la raíz de tu proyecto o directorio src.
Consulta la guía de diccionarios para más detalles.
Opción 3: Seguir usando la antigua biblioteca i18n por ahora, y solo migrar 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 similar a la Opción 2, pero solo migrar parte de tu proyecto a gt-next.
Por ejemplo, puedes seguir usando la antigua biblioteca i18n para algunos componentes, y solo usar gt-next para otros y para contenido nuevo.
Esta opción no es recomendada, ya que tendrás que gestionar dos bibliotecas i18n diferentes en tu proyecto, lo cual puede ser complejo y llevar a errores.
Consejos de 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 sea mucho más fácil en el futuro, y hará que tu 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 diccionarios existentes.
Lo ofrecemos como una forma de hacer la migración más fácil, pero no recomendamos usarlo para contenido nuevo.
3. Usando IA
Si estás usando IA para ayudarte a migrar tu proyecto, tenemos un LLMs.txt y LLMs-full.txt disponibles en:
Estos archivos contienen el contenido completo de esta documentación, por lo que tu herramienta de IA tendrá acceso a toda la información que necesita para ayudarte a migrar tu proyecto.
¿Qué te parece esta guía?