Introducción

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

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

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 ofrecer capacidades 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)

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

import { GTProvider } from 'gt-react';

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

Importante: El proveedor debe envolver toda tu aplicación y ubicarse lo más alto 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 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 de variables como <Num>, <DateTime> y <Currency> para el formateo dinámico de contenido.

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 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 base de código.

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('¡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 que se almacenan 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-react';

const navItems = [
  { label: msg('Inicio'), href: '/' },
  { label: msg('Acerca de'), href: '/acerca-de' },
  { label: msg('Contacto'), href: '/contacto' }
];

// Decodifica y usa 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 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 de una clave determinada.

const diccionario = {
  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.

Consulta la guía de diccionarios 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 cadenas compartidas con la función msg: Guía de cadenas compartidas