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 de withGTConfig para obtener 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.
GTProvider y withGTConfig trabajan juntos para proporcionar contexto a tu aplicación.
Este contexto incluye:
- Gestionar la configuración regional actual del usuario
- Las traducciones relevantes para esa configuración regional
- Contexto para el hook
useGT - Contexto para el hook
useDict
Primero, agrega el componente GTProvider al layout raíz de tu aplicación. Debe colocarse lo más alto posible en el á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 layouts raíz, coloca el GTProvider en cada uno de ellos.
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 librería gt-next.
{
"defaultLocale": "en",
"locales": ["fr", "es"]
}Debes personalizar defaultLocale y locales para que coincidan con tu proyecto. Consulta la lista de configuraciones regionales compatibles para obtener más información.
withGTConfig detectará automáticamente el archivo gt.config.json en tu proyecto y lo usará para configurar el SDK.
Variables de entorno
Configura las siguientes variables de entorno:
GT_API_KEY="" # Tu clave de API de desarrollador de General Translation
GT_PROJECT_ID="" # Tu ID de proyecto de General Translation¡Asegúrate de que tu variable de clave de API solo esté configurada en tu entorno de desarrollo! No debe configurarse en producción.
Puedes obtener una clave de 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 de API de desarrollo para obtener tu clave de API de desarrollo y el ID de proyecto.
Alternativamente, también puedes usar el comando de la herramienta CLI npx gtx-cli auth para generar una clave de API y un ID de proyecto para tu proyecto, guardados en tu archivo .env.local.
Uso
¡Genial! Si has seguido los pasos anteriores, tu aplicación Next.js ya está configurada para usar gt-next.
El siguiente paso es internacionalizar tu contenido. Aquí, daremos una breve descripción 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 deseas traducir dentro del componente <T>.
import { T } from 'gt-next';
<T>
<div>Your content</div>
</T>Si tienes contenido dinámico, necesitarás usar componentes de variable 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 obtener más información.
Hook useGT
El hook useGT es un hook de React que devuelve una función que puede usarse para traducir cadenas de texto.
import { useGT } from 'gt-next/client';
const translate = useGT();
translate('Hello, world!');El hook useGT es un hook del lado del cliente, y solo debe usarse en componentes del lado del cliente.
Para componentes del lado del servidor, utiliza la función asíncrona getGT() en su lugar.
Consulta la guía Traduciendo cadenas para obtener más información.
Utilizar la funcionalidad de recarga en caliente de traducciones 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?