Introducción

El SDK de React de General Translation es una biblioteca de código abierto de internacionalización (i18n) para aplicaciones React.

Ofrece un conjunto completo de herramientas para internacionalizar tu aplicación de React de forma sencilla y mantenible, con paridad de funcionalidades respecto a otras bibliotecas de i18n populares.

El SDK puede usarse de forma independiente, sin la plataforma de General Translation, y se comporta de forma 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

Conceptos

Hay 5 conceptos clave que debes comprender sobre el SDK.

El componente <GTProvider>

El componente <GTProvider> proporciona el contexto de traducción a tu aplicación, incluido el idioma actual y las traducciones relevantes.

import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* El contenido de tu aplicación */}
      </div>
    </GTProvider>
  );
}

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 componente raíz App.

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 se puede usar para envolver cualquier elemento JSX y renderizará automáticamente el contenido del elemento en un idioma admitido.

Ejemplos

<T>
  <div>¡Hola, mundo!</div>
</T>

<T>
  <div>
    <h1> Aquí tienes 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 formatear contenido dinámico.

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 sacrificios.

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 difícil 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 cadenas 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 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 múltiples lugares de tu aplicación.

// Marcar cadenas para traducción
import { msg } from 'gt-react';

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-react';

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 las decodifica.

Consulta la guía de shared strings 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 recuperar traducciones de una clave determinada.

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.

Consulta la guía de dictionaries para conocer más 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 React 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