Uso de Ramas

Descripción general

Los componentes de ramificación en gt-react permiten la renderización dinámica de contenido según condiciones específicas. Estos componentes incluyen:

• <Branch>: Renderiza contenido según una prop branch coincidente.
• <Plural>: Renderiza contenido según las reglas de pluralización para un número dado.

Ambos componentes ofrecen herramientas potentes para gestionar lógica condicional y contenido dinámico en aplicaciones localizadas.

En esta guía, cubriremos:

¿Qué son los componentes de rama?

Los componentes de rama eligen dinámicamente qué contenido renderizar basándose en una condición o valor específico.

<Branch>

El componente <Branch> te permite renderizar diferentes contenidos basados en un valor branch proporcionado. Si no se encuentra una rama coincidente, se renderiza el contenido children de respaldo.

Por ejemplo, el componente <Branch> es perfecto para renderizado condicional basado en el estado de la aplicación, preferencias del usuario o cualquier dato dinámico.

El caso de uso más común es utilizarlo para reemplazar un operador ternario o condicional.

<Plural>

El componente <Plural> extiende la funcionalidad de <Branch> manejando automáticamente la pluralización y la concordancia numérica. Utiliza el valor n proporcionado para determinar qué forma plural mostrar, basándose en reglas específicas del idioma.

Por ejemplo, el componente <Plural> es ideal para renderizar texto en singular y plural dinámicamente, como "1 elemento" vs. "2 elementos".

Los componentes Plural a menudo se combinan con componentes <Num> para localizar un número y su texto correspondiente.

Uso con <T>

Los componentes <Branch> y <Plural> deben usarse dentro de un componente <T> para sanear el contenido dinámico para la traducción.

Cuando se usan dentro de un componente <T>, el contenido se traduce y renderiza automáticamente en el idioma seleccionado por el usuario.

Cuando se usan de forma independiente, simplemente renderizarán el contenido tal cual, sin traducirlo.

Cómo usar componentes de ramificación

Lógica de ramificación con <Branch>

El componente <Branch> se utiliza para cambiar contenido de forma flexible basándose en un valor branch.

Puedes definir múltiples ramas posibles, y el componente renderizará el contenido correspondiente a la clave de rama coincidente.

Además, puedes usar otros componentes variables en combinación con el componente <Branch>.

const branch: 'option1' | 'option2' = 'option1';
<T>
  <Branch 
    branch={branch}
    option1={<p>Option 1</p>}
    option2={<p>Option 2</p>}
  >
    Fallback content
  </Branch>
</T>

El componente <Branch> debe usarse dentro de un componente <T>. Esto permite que el contenido se traduzca automáticamente.

Consulta la Referencia de API para más detalles.

Pluralización con <Plural>

El componente <Plural> automatiza la lógica de pluralización basada en el valor de n. El componente elige dinámicamente la forma plural apropiada para el número y el idioma dados.

const count: number = 1;
<T>
  <Plural
    n={count}
    singular={<><Num>{1}</Num> item.</>}
    plural={<><Num>{count}</Num> items.</>}
    // Additional options
    zero={<><Num>{count}</Num> items.</>}
    one={<><Num>{count}</Num> item.</>}
    two={<><Num>{count}</Num> items.</>}
    few={<><Num>{count}</Num> items.</>}
    many={<><Num>{count}</Num> items.</>}
    other={<><Num>{count}</Num> items.</>}
    dual={<><Num>{count}</Num> items.</>}
  />
</T>

Las formas plurales disponibles dependen del idioma y siguen las reglas de pluralización CLDR de Unicode.

Consulta la Referencia de API para más detalles.

Cuándo usar componentes de ramificación

Los componentes de ramificación son importantes para gestionar contenido dinámico en tu aplicación.

Cuando necesites mostrar diferentes contenidos basados en una condición, usa <Branch>.

Estas condiciones pueden basarse en un componente variable, un booleano o una función.

Por ejemplo, si tu código tiene un operador ternario o renderizado condicional, puedes usar <Branch> para reemplazarlo.

const isActive = true;
// Ternary operator
<Branch branch={isActive} true={<p>The user is active.</p>} false={<p>The user is inactive.</p>}>
  <p>Status unknown.</p>
</Branch>

// Conditional rendering
<Branch branch={isActive} true={<p>The user is active.</p>}>
  <></>
</Branch>

// Ternary operator
const isActive = true;
{isActive ? <p>The user is active.</p> : <p>The user is inactive.</p>}

// Conditional rendering
{isActive && <p>The user is active.</p>}

Si quieres renderizar contenido con pluralización correcta, usa <Plural>.

const count = 1;
<Plural n={count} one={<p>1 item</p>} other={<p>{count} items</p>} />

const count = 1;
{count === 1 ? <p>1 item</p> : <p>{count} items</p>}

Ejemplos

<Branch>

import { T, Branch, Var } from 'gt-react';

export default function UserStatus() {
  const [status, setStatus] = useState<'active' | 'inactive' | undefined>(undefined);
  const [name, setName] = useState<string>('John Doe');
  return (
    <T>
      <Branch
        branch={status}
        active={<p>The user <Var>{name}</Var> is active.</p>}
        inactive={<p>The user <Var>{name}</Var> is inactive.</p>}
      >
        <p>Status unknown.</p>
      </Branch>
    </T>
  );
}

En el ejemplo anterior, el componente <Branch> cambia dinámicamente entre 3 contenidos renderizados según el valor de status.

Cuando status es "active", el componente renderiza:

<p>The user <Var>{name}</Var> is active.</p>

Cuando status es "inactive", el componente renderiza:

<p>The user <Var>{name}</Var> is inactive.</p>

Cuando status no es ni "active" ni "inactive", el componente muestra el contenido alternativo:

<p>Status unknown.</p>

Como el componente <Branch> está envuelto en un componente <T>, el contenido renderizado se traduce automáticamente en contexto.

En este ejemplo, se muestran diferentes descripciones según el plan de suscripción del usuario.

import { Branch } from 'gt-react';

export default function SubscriptionDetails() {
  const [plan, setPlan] = useState<'free' | 'premium' | 'enterprise' | undefined>(undefined);
  return (
    <Branch
      branch={plan}
      free={<p>You are on the Free plan. Upgrade to unlock more features!</p>}
      premium={<p>You are enjoying the Premium plan with full access to features.</p>}
      enterprise={<p>You are on the Enterprise plan. Contact support for tailored solutions.</p>}
    >
      <p>No subscription plan detected.</p>
    </Branch>
  );
}

• La prop branch determina qué mensaje de plan mostrar.
• Si plan es "free", "premium" o "enterprise", se muestra el mensaje correspondiente.
• Si plan no coincide con ninguno de estos valores, se muestra el contenido alternativo ("No subscription plan detected.").

<Plural>

El componente <Plural> maneja dinámicamente el contenido en singular y plural según el valor de n. Este ejemplo muestra la cantidad de mensajes no leídos en la bandeja de entrada de un usuario.

import { T, Plural, Num } from 'gt-react';

export default function UnreadMessages() {
  const [unreadCount, setUnreadCount] = useState<number>(1);
  return (
    <T>
      <Plural
        n={unreadCount}
        one={<>You have <Num>{unreadCount}</Num> unread message.</>}
        other={<>You have <Num>{unreadCount}</Num> unread messages.</>}
      />
    </T>
  );
}

• La prop n especifica el número de mensajes no leídos.
• Si unreadCount es 1, el componente renderiza: "You have 1 unread message."
• Para cualquier otro valor, renderiza: "You have X unread messages." donde X es el valor de unreadCount formateado por <Num>.

Errores comunes

Valores de rama faltantes

Si no se proporciona un valor de rama o no coincide con ninguna clave, el componente <Branch> renderizará el contenido secundario de respaldo. Asegúrate siempre de que las posibles claves de rama coincidan con los valores pasados a la prop branch.

import { Branch } from 'gt-react';

export default function StatusMessage({ status }) {
  return (
    <Branch
      branch={status}
      active={<p>The user is active.</p>}
      inactive={<p>The user is inactive.</p>}
    >
      <p>Status unknown.</p>
    </Branch>
  );
}

Si status es undefined o un valor distinto de active o inactive, se mostrará el contenido de respaldo "Status unknown.".

Formas plurales faltantes

Recuerda especificar todas las formas plurales necesarias en tu idioma predeterminado. Así es como gt-react garantiza que tu aplicación siempre tenga contenido de respaldo para mostrar.

Por ejemplo, si el inglés es tu idioma predeterminado, deberías proporcionar todas las formas plurales para el inglés.

import { Plural, Num } from 'gt-react';

<Plural
  n={count}
  one={<>You have <Num>{count}</Num> unread message.</>}
  other={<>You have <Num>{count}</Num> unread messages.</>}
/>

Aquí, hemos proporcionado las formas plurales one y other para el inglés.

Alternativamente, también puedes proporcionar singular y plural para el inglés.

Notas

• Los componentes Branch son esenciales para gestionar contenido dinámico y localizado en las aplicaciones.
• El componente <Branch> es altamente flexible y puede adaptarse a diversas condiciones y estados.
• El componente <Plural> simplifica la pluralización al seguir automáticamente las reglas específicas de la localidad.
• Siempre incluye una prop children de respaldo para un mejor manejo de errores y experiencia de usuario.

Próximos pasos

• Consulta <Branch> y <Plural> en la Referencia de API para más detalles.
• Aprende más sobre las reglas de pluralización y lógica de ramificación en Reglas de Pluralización Unicode CLDR.
• Explora cómo usar Componentes Variables.