Descripción general
Descripción general del SDK de Next.js de General Translation
Introducción
El SDK de Next.js de General Translation es una biblioteca de internacionalización (i18n) de código abierto para aplicaciones Next.js.
Ofrece un conjunto completo de herramientas para internacionalizar tu aplicación de Next.js de forma sencilla y mantenible, con paridad de funciones respecto a otras bibliotecas populares de i18n. Basado en el React SDK, añade características específicas para Next.js.
El SDK puede usarse de forma independiente, sin la plataforma de General Translation, y se comporta de manera similar a otras bibliotecas de i18n.
No obstante, también se integra con nuestra plataforma para ofrecer funciones avanzadas:
- Recarga en caliente de traducciones en desarrollo
- Traducciones automáticas con IA
- Sincronización de traducciones con la plataforma de General Translation
- Integración nativa con nuestro CDN de traducciones
- Traducción a demanda de componentes de React en producción (del lado del servidor)
Conceptos
Hay 6 conceptos clave que debes comprender sobre el SDK.
Inicialización con withGTConfig
El componente <GTProvider>
El componente <T>
El hook useGT
La función msg para cadenas compartidas
(Opcional) El hook useTranslations
Inicialización con withGTConfig
La función withGTConfig inicializa el SDK en tu aplicación Next.js.
Agrégala a tu archivo next.config.[js|ts] para configurar el SDK:
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Tus opciones de next.config.ts
};
export default withGTConfig(nextConfig, {
// Tu configuración de GT
});Consulta la Referencia de API de withGTConfig para obtener más información.
El componente <GTProvider>
El componente <GTProvider> proporciona el contexto de traducción a tu aplicación, incluido el idioma actual y las traducciones pertinentes.
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}Importante: El provider debe envolver toda tu aplicación y ubicarse lo más arriba posible en el árbol de componentes, por ejemplo, en el layout raíz.
El provider solo es necesario para funcionalidades del lado del cliente. Las aplicaciones exclusivamente del lado del servidor no lo requieren, aunque puede incluirse igualmente.
Consulta la Referencia de API de GTProvider para obtener más información.
El componente <T>
El componente <T> es la forma recomendada de traducir contenido en tu aplicación.
Es un componente de React que puede usarse para envolver cualquier elemento JSX y que renderiza automáticamente el contenido del elemento en un idioma compatible.
Ejemplos
<T>
<div>¡Hola, mundo!</div>
</T><T>
<div>
<h1> Aquí hay una imagen </h1>
<img src="https://example.com/image.png" alt="Ejemplo" />
</div>
</T><T>
El formato se puede aplicar fácilmente con el componente `<T>`.
<Num>{1000}</Num>
<DateTime>{new Date()}</DateTime>
<Currency currency="USD">{1000}</Currency>
</T>El componente <T> funciona con componentes variables como <Num>, <DateTime> y <Currency> para formatear contenido dinámico.
Consulta la guía del componente <T> para conocer las diferentes formas de usar el componente <T>.
El hook useGT
El hook useGT es un hook de React que puede usarse de forma similar al componente <T>, con algunas salvedades.
El hook devuelve una función que puede usarse para traducir cadenas de texto.
const t = useGT();
t('¡Hola, mundo!');En comparación con el componente <T>, el hook useGT ofrece más flexibilidad en tu código.
Por ejemplo, si tienes una estructura de datos compleja con cadenas anidadas, usar un componente <T> sería más complicado.
const t = useGT();
const data = {
title: t('¡Hola, mundo!'),
description: t('Esta es una descripción'),
};Consulta la guía de strings para saber más sobre el hook useGT.
La función msg
La función msg se utiliza para marcar cadenas para traducción que se usan en varios componentes o que se almacenan en objetos de configuración.
Esto es especialmente útil para contenido compartido como etiquetas de navegación, mensajes de formularios o cualquier texto que aparezca en varios lugares de tu aplicación.
// Marcar cadenas para traducción
import { msg } from 'gt-next';
const navItems = [
{ label: msg('Inicio'), href: '/' },
{ label: msg('Acerca de'), href: '/about' },
{ label: msg('Contacto'), href: '/contact' }
];// Decodifica y utiliza las cadenas marcadas
import { useMessages } from 'gt-next';
function Navigation() {
const m = useMessages();
return (
<nav>
{navItems.map(item => (
<a key={item.href} href={item.href}>
{m(item.label)}
</a>
))}
</nav>
);
}La función msg codifica cadenas con metadatos de traducción, y useMessages (o getMessages para componentes del servidor) las decodifica.
Consulta la guía de cadenas compartidas para obtener más información sobre la función msg.
El hook useTranslations
El hook useTranslations es un hook de React que devuelve una función para obtener traducciones a partir de una clave dada.
const dictionary = {
hello: {
world: '¡Hola, mundo!',
},
};const translate = useTranslations();
translate('hola.mundo');Este comportamiento es similar al de otras bibliotecas de traducción, como react-i18next y next-intl.
No recomendamos usar el hook useTranslations en tu aplicación. El uso frecuente del hook useTranslations hará que tu base de código sea más difícil de mantener
y generará una gran deuda técnica.
En su lugar, recomendamos usar el componente <T> o el hook useGT.
Si estás migrando desde otra biblioteca de i18n, el hook useTranslations es un reemplazo directo y puede ser útil para migrar tu base de código de forma incremental.
Consulta la guía de dictionaries para obtener más información sobre el hook useTranslations.
Consulta la Referencia de API de useTranslations para más información.
Próximos pasos
- Aprende a configurar tu proyecto de Next.js con el SDK: Inicio rápido
- Aprende a traducir contenido JSX con el componente
<T>: Guía de traducción de JSX - Aprende a traducir cadenas con el hook
useGT: Guía de traducción de cadenas - Aprende sobre cadenas compartidas con la función
msg: Guía de cadenas compartidas
¿Qué te ha parecido esta guía?