Traduciendo JSX

Descripción general

Esta guía te llevará paso a paso por el uso del componente <T> para internacionalizar contenido JSX.

Al final de esta guía, sabrás la sintaxis correcta para usar el componente <T> y qué debes evitar.

Cubriremos lo siguiente:

Si buscas información sobre cómo usar Variable Components o Branching Components, consulta sus respectivas guías.

Cómo usar el componente <T>

Supongamos que tienes algún contenido HTML que deseas traducir.

function Greeting() {
  return <p>Hello, world!</p>;
}

Todo lo que tienes que hacer es envolver el contenido en un componente <T>.

import { T } from 'gt-next';

function Greeting() {
  return <T><p>Hello, world!</p></T>;
}

Dependiendo del idioma actual que tu usuario haya seleccionado, esto mostrará la traducción correspondiente. Consulta cambiar idiomas para obtener más información sobre cómo permitir que tus usuarios cambien de idioma.

Opciones adicionales

Contexto

En algunos casos, es posible que desees proporcionar contexto adicional a la traducción. Esto se puede hacer pasando una prop context al componente <T>.

<T context="toast, as in a pop-up notification">
  Click on the toast to dismiss it.
</T>

Esto es útil en casos donde las palabras pueden tener varios significados dependiendo del contexto. Por ejemplo, "toast" puede referirse a la comida o a una notificación emergente.

La prop context es útil para que la IA entienda la intención de la traducción.

id

También puedes pasar una prop id al componente <T>. Esto es útil para fines de depuración y facilita la edición de la traducción.

<T id="toast">
  Click on the toast to dismiss it.
</T>

Cuándo usar el componente <T>

Aunque el componente <T> es muy flexible, no siempre es la mejor solución.

Siempre debes intentar usar el componente <T> cuando tengas cualquier contenido estático en HTML o JSX.

Cuándo no usar el componente <T>

NO uses el componente <T> cuando tengas contenido dinámico no seguro.

Aquí, contenido dinámico significa cualquier contenido que podría cambiar en tiempo de ejecución. Esta regla no aplica si estás usando Componentes de Variable o Componentes de Ramificación.

Los siguientes ejemplos muestran un uso no válido del componente <T>:

<T>
  <p>Your username is {username}</p>
</T>

<T>
  <p>Current date: {new Date().toLocaleDateString()}</p>
</T>

<T>
  <p>Logical Expressions: {username === 'admin' ? 'Yes' : 'No'}</p>
</T>

<T>
  <p>Conditional Rendering: {isAdmin ? 'Yes' : 'No'}</p>
</T>

const chatMessage = getChatMessageFromServer();
<T>
  <p>{chatMessage}</p>
</T>

Ejemplos

Aquí tienes algunos ejemplos de cómo usar el componente <T>. Todos estos son correctos.

1. Contenido HTML

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

<p>Hello, world!</p>

2. Contenido JSX simple

<T>
  <Button>¡Haz clic!</Button>
</T>

<Button>Click me!</Button>

3. Contenido JSX complejo

<T>
  <Tooltip>
    <TooltipTrigger>
      <div className="flex items-center gap-2 rounded-full bg-destructive px-3 py-1.5 text-sm text-destructive-foreground">
        <AlertCircle className="h-4 w-4" />
        <span>Uso gratuito</span>
      </div>
    </TooltipTrigger>
    <TooltipContent>
      <p>
        Estás cerca de alcanzar tu límite mensual gratuito. Por favor,
        actualiza tu plan para evitar cualquier interrupción en tu
        servicio.
      </p>
    </TooltipContent>
  </Tooltip>
</T>

<Tooltip>
  <TooltipTrigger>
    <div className="flex items-center gap-2 rounded-full bg-destructive px-3 py-1.5 text-sm text-destructive-foreground">
      <AlertCircle className="h-4 w-4" />
      <span>Free Usage</span>
    </div>
  </TooltipTrigger>
  <TooltipContent>
    <p>
      You are nearing your free monthly limit. Please
      upgrade your plan to avoid any disruptions to your
      service.
    </p>
  </TooltipContent>
</Tooltip>

Consideraciones de producción

Despliegue en producción

Asegúrate de ejecutar el comando de traducción antes de desplegar en 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 compilación.

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

Para una guía más detallada sobre cómo desplegar tu aplicación, consulta el tutorial de Despliegue. Para más información sobre el comando, 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 de inmediato. La biblioteca hace 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, todas las traducciones que utiliza el componente <T> se completan en tiempo de compilació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 la General Translation API para su traducción. Esto podría no ser deseable para mostrar 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 ningún dato sensible se envíe a la General Translation API para su traducción. La localización de cualquier contenido envuelto en un componente de variable se maneja localmente.

Errores Comunes

Solo descendientes directos

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

Vamos a ilustrar esto con un ejemplo:

function UntranslatedContent() {
  return (
    <p>This content is not translated</p>
  );
}

export default function DisplayGreetings() {
  return (
    <T>
      <h1>Hello, this text will be translated</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.

¿Cuál es la solución?

Envuelve el texto directamente en el componente <T>, así:

function TranslatedContent() {
  return (
    <T>
      <p>This content <b>IS</b> translated</p>
    </T>
  );
}

export default function DisplayGreetings() {
  return (
    <>
      <T>
        <h1>Hello, this text will be translated</h1>
      </T>
      <TranslatedContent />
    </>
  );
}

Componentes <T> anidados

No está permitido anidar componentes <T>. Debido al sistema de renderizado de React, esto puede llevar a comportamientos inesperados y problemas de rendimiento.

Aquí tienes un ejemplo de lo que no debes hacer:

function SomeComponent() {
  return (
    <T>
      Hello, friend!
    </T>
  );
}

export default function NestedTranslation() {
  return (
    <T>
      <T> {/* ¡No hagas esto! */} 
        Hello, world! 
      </T>
      <SomeComponent /> {/* Esto también cuenta. ¡No hagas esto! */}
    </T>
  );
}

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

Traducir contenido dinámico

Si intentas envolver contenido dinámico con el componente <T>, la herramienta CLI dará un error.

Por ejemplo, lo siguiente dará un error:

const username = 'John Doe';
<T>
  <p>Your username is {username}</p>
</T>

Para solucionar esto, intenta usar Componentes de Variables o Componentes de Ramas para envolver el contenido dinámico.

Alternativamente, si tu contenido realmente es dinámico y necesita ser traducido bajo demanda, puedes usar el componente <Tx>.

Resumen

• Los componentes <T> se utilizan para internacionalizar contenido JSX arbitrario.
• No se deben usar los componentes <T> para contenido dinámico, a menos que se utilicen componentes de variables o componentes de ramificación.
• En desarrollo, el componente <T> traducirá el contenido bajo demanda.
• En producción, todas las traducciones que utiliza el componente <T> se completan en tiempo de compilación.

Próximos pasos

• Lee sobre la API para el componente <T>.
• Explora los Componentes de Variable y los Componentes de Ramificación.
• Aprende sobre cómo traducir cadenas.