Inicio rápido con Next.js
Internacionaliza fácilmente tu aplicación Next.js con gt-next
Descripción general
Esta guía de inicio rápido te guiará a través del proceso de configuración de tu aplicación Next.js con gt-next.
Al final de esta guía, tendrás una aplicación Next.js lista para comenzar a traducir contenido.
En esta guía, cubriremos lo siguiente:
Instalación
Configuración
Uso
Pruebas de tu aplicación
Despliegue
Requisitos previos
- Una aplicación Next.js que utilice el App Router
- Conocimientos básicos de Next.js y JavaScript
Instalación
Instala los paquetes gt-next y 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-cliConfiguración Automática: Tenemos un Asistente de Configuración experimental que puede ayudarte a configurar tu proyecto con gt-next.
Pruébalo ejecutando npx gtx-cli@latest. Aún necesitarás internacionalizar las cadenas de texto manualmente, pero te ayudará a comenzar.
Consulta la guía de referencia del Asistente de Configuración para más información.
Alternativamente, si quieres que tu herramienta de IA como Claude Code, Cursor, o Windsurf configure automáticamente tu proyecto, puedes usar nuestro servidor mcp.
Configuración
withGTConfig
La función withGTConfig es una función que se utiliza para inicializar el SDK en una aplicación Next.js.
Coloca esto en tu archivo next.config.[js|ts].
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Your next.config.ts options
};
export default withGTConfig(nextConfig, {
// Additional GT configuration options
});Consulta la Referencia de la API withGTConfig para más información.
GTProvider
gt-next también exporta un componente GTProvider. Este componente se utiliza para proporcionar contexto a los componentes del lado del cliente en tu aplicación Next.js.
El GTProvider y withGTConfig trabajan juntos para proporcionar contexto a tu aplicación.
Este contexto incluye:
- Gestión de la configuración regional actual del usuario
- Las traducciones relevantes para esa configuración regional
- Contexto para el hook
useGT - Contexto para el hook
useTranslations
Primero, agrega el componente GTProvider al diseño raíz de tu aplicación. Debe colocarse lo más alto posible en tu árbol de componentes.
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}Si tienes múltiples diseños raíz, coloca el GTProvider en cada uno.
A continuación, crea un archivo gt.config.json en la raíz de tu proyecto.
Este archivo se utiliza para configurar tanto la herramienta gtx-cli como la biblioteca gt-next.
{
"defaultLocale": "en",
"locales": ["fr", "es"]
}Debes personalizar el defaultLocale y locales para que coincidan con tu proyecto. Consulta la lista de configuraciones regionales compatibles para más información.
withGTConfig detectará automáticamente el archivo gt.config.json en tu proyecto y lo utilizará para configurar el SDK.
Variables de Entorno
Establece las siguientes variables de entorno:
GT_API_KEY="" # Your General Translation Developer API key
GT_PROJECT_ID="" # Your General Translation project ID¡Asegúrate de que tu variable de clave API solo esté configurada en tu entorno de desarrollo! No debe estar configurada en producción.
Puedes obtener una clave API gratuita y un ID de proyecto creando una cuenta de General Translation.
Después de crear una cuenta, navega a la página de Claves API de Desarrollo para obtener tu clave API de desarrollo y el ID del proyecto.
Alternativamente, también puedes usar el comando de la herramienta CLI npx gtx-cli auth para generar una clave API y un ID de proyecto para tu proyecto, guardados en tu archivo .env.local.
Uso
¡Excelente! Si has seguido los pasos anteriores, tu aplicación Next.js ahora está configurada para usar gt-next.
El siguiente paso es internacionalizar tu contenido. Aquí, daremos una breve descripción general de las diferentes formas de traducir contenido en tu aplicación.
Componente <T>
El componente <T> es el componente principal para traducir contenido JSX en tu aplicación.
Para usarlo, simplemente envuelve el JSX que quieres traducir en el componente <T>.
import { T } from 'gt-next';
<T>
<div>Your content</div>
</T>Si tienes contenido dinámico, necesitarás usar componentes de variables para pasar los valores dinámicos.
import { T, Var } from 'gt-next';
<T>
<div>Hello, <Var>{name}</Var>!</div>
</T>Consulta la guía Traduciendo JSX para más información.
Hook useGT
El hook useGT es un hook de React que devuelve una función que puede ser usada para traducir cadenas de texto.
import { useGT } from 'gt-next'
const translate = useGT();
translate('Hello, world!');El hook useGT puede ser usado tanto en componentes del lado del cliente como del lado del servidor.
Para componentes asíncronos, usa la función asíncrona getGT() en su lugar.
Consulta la guía Traduciendo Cadenas de Texto para más información.
Utilizar la funcionalidad de traducción con recarga en caliente será útil para internacionalizar tu aplicación.
Para habilitar esto, asegúrate de tener las variables de entorno GT_API_KEY y GT_PROJECT_ID configuradas en tu entorno de desarrollo.
Probando tu aplicación
¡Felicidades! 🥳 Si has seguido los pasos anteriores, ¡tu aplicación ahora es multilingüe! Veámosla en acción.
Ver tu aplicación en otro idioma
Agrega el componente <LocaleSelector> a tu aplicación.
Esto te permitirá seleccionar un idioma diferente para tu aplicación.
Consejo: También puedes omitir este paso y simplemente cambiar el idioma en la configuración de tu navegador.
Inicia tu aplicación Next.js en modo desarrollo.
npm run dev yarn run dev bun run dev pnpm run dev Abre tu aplicación en tu navegador preferido (usualmente en http://localhost:3000).
Solución de problemas
Despliegue
¡Genial! Si estás satisfecho con tus traducciones y la funcionalidad de tu aplicación, ahora puedes desplegar tu aplicación.
El comportamiento de gt-next en producción es ligeramente diferente al de desarrollo. Específicamente, no se realizarán traducciones en tiempo de ejecución (con la excepción del componente <Tx> y la función tx).
Esto significa que deberás traducir tu contenido antes de desplegar tu aplicación, durante el proceso de compilación.
Por suerte, la herramienta gtx-cli tiene un comando translate que puede usarse para traducir tu contenido automáticamente.
Primero, necesitarás obtener una clave API de Producción desde la plataforma General Translation.
Ten en cuenta que esta clave es diferente de tu clave API de Desarrollo, y comienza con gtx-api-, en lugar de gtx-dev-.
Lee sobre la diferencia entre las claves de Desarrollo y Producción aquí.
Agrega esta variable de entorno a tu pipeline de CI/CD.
GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>¡Asegúrate de que GT_API_KEY NO esté prefijada con NEXT_PUBLIC_!
Si lo está, corres el riesgo de exponer tu clave API al público.
Ejecuta el comando translate para traducir tu contenido.
npx gtx-cli translatePuedes configurar el comportamiento del comando translate con el archivo gt.config.json.
Consulta la guía de referencia de la herramienta CLI para más información.
Agrega el comando translate a tu proceso de compilación.
{
"scripts": {
"build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
}
}Resumen
- En esta guía, cubrimos cómo configurar tu aplicación Next.js con
gt-next - Hablamos brevemente sobre las diferentes formas de traducir contenido en tu aplicación.
- También explicamos cómo desplegar tu aplicación después de haber internacionalizado tu contenido.
Próximos pasos
- Aprende cómo traducir contenido JSX con el componente
<T>: Traducir JSX - Aprende cómo traducir cadenas de texto con el hook
useGT: Traducir cadenas - Aprende cómo usar traducciones locales: Traducciones locales
¿Qué te parece esta guía?