Referencia de <T>

Resumen

Este artículo profundizará en cómo usar el componente <T> en la biblioteca gt-react. Siéntase libre de saltar por esta página según sea necesario. Cubriremos lo siguiente:

• El componente <T>
• Patrones de diseño
• Consideraciones de producción
• Algunos ejemplos
• Errores comunes

Si está buscando cómo usar Componentes Variables o Componentes de Ramificación, por favor consulte sus respectivos artículos.

¿Qué es el componente <T>?

El componente <T> es la forma principal de traducir texto y contenido en la biblioteca gt-react. Permite la traducción en línea de texto y estructuras JSX, proporcionando una forma más directa de gestionar traducciones en tu aplicación. Esto a menudo es más conveniente para el desarrollador ya que permite un control más directo sobre el contenido de la traducción.

El componente <T> admite texto estático, estructuras JSX y traducciones conscientes del contexto. Cuando no hay una traducción disponible, muestra el contenido en el idioma predeterminado de la aplicación de manera elegante.

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

Patrones de Diseño

En esta sección, detallaremos patrones de diseño comunes utilizados con el componente <T>. Esto también tocará temas que están tangencialmente relacionados con el componente <T>, pero igualmente importantes, como la traducción de cadenas, la traducción de contenido de manera avanzada y las preocupaciones de privacidad.

Envolviendo tus componentes <T> en un <GTProvider>

<T> se utiliza para traducir texto estático y estructuras JSX. <T> DEBE estar envuelto en un <GTProvider> a un nivel superior. Nuestro consejo es envolver tu aplicación en un <GTProvider> en el nivel raíz para proporcionar este contexto.

import { GTProvider } from "gt-react"; 
import MyApp from "./MyApp";
 
export default function App() {
  return (
    <GTProvider>
      <MyApp />
    </GTProvider> 
  );
}

Variables en Componentes <T>

Los componentes de variables se pueden usar en componentes <T> para (1) mostrar valores dinámicos y/o (2) marcar contenido que no debe ser traducido. Piensa en cosas como el nombre de un usuario: es (1) diferente de persona a persona y (2) no debería cambiar incluso cuando el idioma cambia.

import { T, Var } from 'gt-react';
 
export default function DynamicGreeting({ user }) {
  return (
    <T>
      ¡Hola, <Var>{user.name}</Var>! // [!code highlight]
    </T>
  );
}

Hay muchos componentes de variables: <Var>, <Num>, <Currency> y <DateTime>. Algunos de estos reformatearán automáticamente el contenido según la configuración regional del usuario. Otros simplemente marcarán el contenido como "no traducir". Además, estos componentes no necesariamente necesitan estar envueltos en un componente <T> para reformatear el contenido.

Lee más sobre esto en este artículo sobre componentes de variables.

Ramificación en Componentes <T>

Los componentes de ramificación se pueden usar para mostrar contenido diferente basado en condiciones para traducciones. Estos incluyen los componentes <Plural> y <Branch>. Usamos estos componentes porque permiten un proceso de traducción más optimizado.

Por ejemplo, el componente <Plural> te permite marcar una oración que debe pluralizarse cuando se realiza la traducción.

import { T, Plural } from 'gt-react';
 
export default function Count({ num }) {
  return (
    <T>
      <Plural
        n={num} // <-- variable a verificar
        singular={<p>Hay un artículo.</p>}  
        plural={<p>Hay varios artículos.</p>}  
      />
    </T>
  );
}

También es útil ya que estandariza tu lógica de pluralización en toda tu aplicación en tu idioma base.

Puedes especificar diferentes opciones dependiendo de qué componente uses. Lee más sobre esto en el artículo Componentes de Ramificación.

Traduciendo Cadenas

Si deseas traducir solo una cadena, puedes usar useGT(). Se utiliza para traducir cadenas en tiempo de compilación.

function Greeting() {
  const t = useGT();
  return <p>{t('¡Hola, mi amigo!')}</p>; 
}

Para más información, puedes consultar nuestra guía sobre la traducción de cadenas.

¡Eso es todo! Has traducido exitosamente tu aplicación al francés, español y japonés.

Para una guía más detallada sobre cómo desplegar tu aplicación, por favor consulta la guía de Despliegue. Para más información sobre el comando, por favor consulta la guía de referencia de la Herramienta CLI.

Añadiendo ids a Componentes <T>

Un truco útil para depuración es añadir una prop id a tus componentes <T>. Esto te permite rastrear qué traducciones se están utilizando en tu aplicación. También te permite usar el Editor de Traducciones para hacer cambios en tus traducciones sin volver a desplegar.

import { T } from 'gt-react';
 
export default function Greeting() {
  return (
    <T id="greeting">
      ¡Hola, mundo!
    </T>
  );
}

Consideraciones de producción

Desplegando a producción

Asegúrate de ejecutar el comando de traducción antes de desplegar a producción, para que todas las traducciones estén disponibles en tiempo de ejecución. Recomendamos agregarlo a tu pipeline de CD o como parte de tu script de construcción.

{
  "scripts": {
    "build": "npx gtx-cli translate --languages fr es ja && <YOUR_BUILD_COMMAND>",
  }
}

¡Eso es todo! Has traducido exitosamente tu aplicación al francés, español y japonés.

Para una guía más detallada sobre cómo desplegar tu aplicación, por favor consulta la guía de Despliegue. Para más información sobre el comando, por favor consulta la guía de referencia de la Herramienta CLI.

Comportamiento: Desarrollo vs Producción

En desarrollo, el componente <T> traducirá el contenido bajo demanda. Esto significa que cuando el componente se renderiza, realizará una traducción inmediatamente. Hacemos esto por conveniencia para facilitar el desarrollo con otros idiomas.

Para habilitar este comportamiento, solo agrega una clave de API de desarrollo a tu entorno.

En producción, el componente <T> traducirá el contenido en tiempo de construcción. Esto significa que debes ejecutar el comando de traducción antes de desplegar tu aplicación.

Preocupaciones de privacidad

Con algunas excepciones, todo el contenido envuelto en un componente <T> se envía a las APIs de Traducción General para su traducción. Esto podría no ser deseable para renderizar datos sensibles, como nombres de usuario, números de cuenta, etc.

Para evitar este problema, utiliza Componentes de Variable para manejar información privada. Esto asegura que no se envíen datos sensibles a las APIs de Traducción General para su traducción. La localización de todo el contenido envuelto en cualquier Componente de Variable se maneja localmente.

Ejemplos

Uso Básico

El caso de uso más simple para <T> es traducir texto estático.

import { T } from 'gt-react';
 
export default function BasicUsage() {
  return (
    <T>
      Hello, world!
    </T>
  );
}

Este ejemplo asegura que "Hello, world!" se traduzca según la configuración regional del usuario. Por ejemplo, en una configuración regional en español, podría renderizarse como "¡Hola, mundo!".

Contexto

El componente <T> admite contexto adicional para refinar las traducciones. Agregar una prop de contexto permite que el mismo id se resuelva en diferentes traducciones dependiendo del contexto proporcionado.

import { T } from 'gt-react';
 
export default function FormalGreeting() {
  return (
    <T context="formal">
      Hi there!
    </T>
  );
}

Por ejemplo, el contexto "formal" podría producir una traducción como "¡Buen día a todos!", mientras que el mismo id sin contexto podría producir "¡Hola!" en el otro idioma. Por supuesto, no ocurriría ningún cambio para el idioma base.

Componentes Anidados

El componente <T> también puede traducir estructuras JSX. Cualquier hijo de <T> será traducido.

import { T } from 'gt-react';
import CustomButton from './CustomButton';
 
export default function Page() {
  return (
    <T>
      Esto será traducido
      <div>
        <div>
          <div>
            <div>
              <CustomButton>¡Este texto también será traducido!</CustomButton>
            </div>
          </div>
        </div>
      </div>
    </T>
  );
}

Errores Comunes

Solo descendientes directos

El componente <T> solo traduce el texto pasado directamente como un hijo. Esto significa que si tienes contenido dentro de un componente que no se pasa directamente a <T>, no se traducirá.

Vamos a ilustrar esto con un ejemplo:

function UntranslatedContent() {
  return (
    <p>Este contenido no está traducido</p>
  );
}
 
export default function DisplayGreetings() {
  return (
    <T>
      <h1>Hola, este texto será traducido</h1>
      <UntranslatedContent />
    </T>
  );
}

En este ejemplo, el contenido dentro de <UntranslatedContent> no será traducido. Solo el contenido directamente dentro de <T> será traducido, como la etiqueta <h1> y sus hijos.

Esto ocurre debido a cómo React renderiza los componentes. Es un poco complicado, pero la esencia es que React no conoce el contenido de un componente hasta que se ha renderizado. Por lo tanto, los contenidos de componentes como <UntranslatedContent> no se traducen. Sin embargo, cualquier texto directamente entre las dos etiquetas <T> será traducido.

¿Cuál es la solución?

Tu primer instinto podría ser agregar un componente <T> adicional dentro de <UntranslatedContent>, pero esto no se recomienda. Discutimos esto más abajo.

La solución es siempre envolver el texto en el componente <T> directamente, de esta manera:

function TranslatedContent() {
  return (
    <T>
      <p>Este contenido <b>ESTÁ</b> traducido</p>
    </T>
  );
}
 
export default function DisplayGreetings() {
  return (
    <>
      <T>
        <h1>Hola, este texto será traducido</h1>
      </T>
      <TranslatedContent />
    </>
  );
}

¿Qué pasa con las variables?

Las variables son un poco más complicadas porque tienden a cambiar sus valores. Recomendamos usar Componentes de Variables para mostrar valores dinámicos y Componentes de Ramificación para lógica condicional.

Componentes <T> Anidados

No se permite anidar componentes <T>. Debido al sistema de renderizado de react, esto puede llevar a un comportamiento inesperado y problemas de rendimiento al traducir bajo demanda.

Aquí hay un ejemplo de lo que no se debe hacer:

function SomeComponent() {
  return (
    <T>
      ¡Hola, amigo!
    </T>
  );
}
 
export default function NestedTranslation() {
  return (
    <T>
      <T> {/* ¡No hagas esto! */} // [!code highlight]
        ¡Hola, mundo!
      </T>
      <SomeComponent /> {/* Esto aún cuenta. ¡No hagas esto! */} // [!code highlight]
    </T>
  );
}

La solución aquí es eliminar el componente <T> más externo.

Contenido Condicional

Similar a renderizar contenido variable, el contenido condicional dentro de un componente <T> necesita ser manejado adecuadamente. Siempre es una buena práctica envolver el contenido condicional en un Componente de Ramificación para optimizar la traducción del contenido.

import { T, Branch } from 'gt-react';
 
export default function Header({ user }) {
  return (
    <T>
      <h2>
        <Branch
          branch={user.hasAccount}
          true={<p>¡Bienvenido de nuevo, {user.name}!</p>}
          false={<p>Por favor, inicia sesión para continuar.</p>}
        />
      </h2>
    </T>
  );
}

Notas

• Los componentes <T> se utilizan para traducir contenido JSX arbitrario.
• Envuelve tu aplicación con un <GTProvider> para habilitar traducciones.
• <T> traduce contenidos en tiempo de compilación, no en tiempo de ejecución. El desarrollo realizará traducciones bajo demanda para mayor comodidad, pero este no es el caso en producción.

Próximos Pasos

• Explora el artículo de Componentes Variables y la guía de Componentes de Ramificación.
• Aprende sobre traducir cadenas en tu aplicación.