Descripción general
Descripción general del SDK de Next.js de General Translation
Introducción
El SDK de General Translation para Next.js es una biblioteca de internacionalización (i18n) de código abierto para Next.js.
Ofrece un conjunto de herramientas para ayudarte a internacionalizar tu aplicación de Next.js de manera fácil y mantenible, con paridad de características con otras bibliotecas i18n populares. Está construido sobre el React SDK, y ofrece características adicionales específicas para Next.js.
El SDK de Next.js puede ser usado sin la plataforma de General Translation, y actuará de manera muy similar a otras bibliotecas i18n.
Sin embargo, también se integra con nuestra plataforma, ofreciendo características adicionales como:
- 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 bajo demanda de componentes React en producción (en el lado del servidor)
Conceptos
Hay 5 conceptos principales que debes entender sobre el SDK.
Inicialización con withGTConfig
El componente <GTProvider>
El componente <T>
El hook useGT
(Opcional) El hook useDict
Inicialización con withGTConfig
La función withGTConfig es una función que se utiliza para inicializar el SDK en una aplicación Next.js.
Debe colocarse en tu archivo next.config.[js|ts], y se utiliza para configurar el SDK.
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Your next.config.ts options
};
export default withGTConfig(nextConfig, {
// Your GT configuration
});Consulta la Referencia de la API withGTConfig para más información.
El componente <GTProvider>
import { GTProvider } from 'gt-next';El componente <GTProvider> es el componente principal que necesitas agregar a tu aplicación.
Se utiliza para proporcionar al resto de tu aplicación el contexto necesario.
Este contexto incluye el idioma actual y las traducciones relevantes para ese idioma.
El proveedor solo es requerido si estás utilizando características del lado del cliente. Si solo estás utilizando características del lado del servidor, el proveedor no es requerido, pero aún puede ser incluido.
Consideraciones Importantes
- El proveedor debe envolver toda tu aplicación.
- Idealmente, debe colocarse lo más alto posible en el árbol, como en tu layout raíz.
Consulta la página GTProvider para 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 ser usado para envolver cualquier elemento JSX, y automáticamente renderizará el contenido del elemento en un idioma soportado.
Recomendamos usar el componente <T> siempre que sea posible, ya que permite la mayor flexibilidad en las traducciones.
A diferencia de las cadenas de texto, el componente <T> puede ser usado para traducir contenido HTML, haciéndolo mucho más poderoso que las traducciones de cadenas.
Ejemplos
<T>
<div>Hello, world!</div>
</T><T>
<div>
<h1> Here is an image </h1>
<img src="https://example.com/image.png" alt="Example" />
</div>
</T><T>
Formatting can be done easily with the `<T>` component.
<Num>{1000}</Num>
<DateTime>{new Date()}</DateTime>
<Currency>{1000}</Currency>
</T>Consulta la guía de componentes para aprender sobre las diferentes formas de usar el componente <T>.
Consulta la Referencia de API de T para la API del componente <T>.
El hook useGT
El hook useGT es un hook de React que se puede usar de manera similar al componente <T>, con algunas compensaciones.
El hook devuelve una función que se puede usar para traducir cadenas de texto.
const translate = useGT();
translate('Hello, world!');Comparado con el componente <T>, el hook useGT permite más flexibilidad en tu código base.
Por ejemplo, si tienes una estructura de datos compleja con cadenas anidadas, un componente <T> sería más difícil de usar.
const t = useGT();
const data = {
title: t('Hello, world!'),
description: t('This is a description'),
};Consulta la guía de strings para aprender más sobre el hook useGT.
Consulta la Referencia de la API useGT para más información.
El hook useDict
El hook useDict es un hook de React que devuelve una función que puede ser utilizada para recuperar traducciones para una clave dada.
const dictionary = {
hello: {
world: 'Hello, world!',
},
};const translate = useDict();
translate('hello.world');Este comportamiento es similar a otras librerías de traducción, como react-i18next y next-intl.
No recomendamos usar el hook useDict en tu aplicación. El uso frecuente del hook useDict hará que tu código base sea más difícil de mantener,
y llevará a una gran deuda técnica.
En su lugar, recomendamos usar el componente <T> o el hook useGT.
Si estás migrando desde otra librería i18n, el hook useDict es un reemplazo directo y puede ser útil para migrar tu código base de manera incremental.
Consulta la guía de dictionaries para aprender más sobre el hook useDict.
Consulta la Referencia de la API useDict para más información.
Próximos Pasos
- Aprende cómo configurar tu proyecto Next.js con el SDK: Inicio Rápido
- Aprende cómo traducir cadenas de texto con el hook
useGT: Traduciendo Cadenas de Texto - Aprende cómo traducir contenido JSX con el componente
<T>: Traduciendo JSX
¿Qué te parece esta guía?