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 de Next.js.
Ofrece un conjunto completo de herramientas para internacionalizar tu aplicación de Next.js de forma sencilla y mantenible, con paridad de funcionalidades frente a otras bibliotecas populares de i18n. Construido sobre el React SDK, incorpora funciones adicionales específicas de 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.
Sin embargo, también se integra con nuestra plataforma para funciones avanzadas:
- Recarga en caliente de traducciones durante el desarrollo
- Traducciones automáticas con IA
- Sincronización de traducciones con la plataforma de General Translation
- Integración nativa con nuestro CDN de traducciones (red de distribución de contenido)
- Traducción a demanda de componentes de React en producción (en el lado del servidor)
Conceptos
Hay 6 conceptos clave que debes conocer sobre el SDK.
Inicialización con withGTConfig
El componente <GTProvider>
El componente <T>
El hook useGT
La función msg para strings compartidos
(Opcional) El hook useTranslations
Inicialización con withGTConfig
La función withGTConfig inicializa el SDK en tu aplicación Next.js.
Añádela 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 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 proveedor 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 proveedor solo es necesario para funcionalidades del client-side. Las aplicaciones que se ejecutan únicamente en el server-side 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 manera recomendada de traducir contenido en tu aplicación.
Es un componente de React que puede usarse para envolver cualquier elemento JSX y, de forma automática, mostrará 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 de variables como <Num>, <DateTime> y <Currency> para dar formato dinámico al contenido.
Consulta la guía del componente <T> para conocer las distintas 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 algunos compromisos.
El hook devuelve una función que puede usarse para traducir cadenas.
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, sería más complicado usar un componente <T>.
const t = useGT();
const data = {
title: t('¡Hola, mundo!'),
description: t('Esta es una descripción'),
};Consulta la guía de strings para obtener más información 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 se guardan en objetos de configuración.
Esto es especialmente útil para contenido compartido como etiquetas de navegación, mensajes de formulario 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 usa 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 de 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 que puede usarse para obtener traducciones de una clave dada.
const dictionary = {
hello: {
world: '¡Hola, mundo!',
},
};const translate = useTranslations();
translate('hello.world');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 diccionarios 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 las cadenas compartidas con la función
msg: Guía de cadenas compartidas
¿Qué te parece esta guía?