Uso de ramas

Descripción general

Los componentes de ramificación en gt-next 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 según una condición o valor específico.

<Branch>

El componente <Branch> te permite renderizar diferentes contenidos según el valor de branch proporcionado. Si no se encuentra una rama coincidente, se renderiza el contenido de children como alternativa.

Por ejemplo, el componente <Branch> es perfecto para renderizado condicional basado en el estado de la aplicación, las 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> amplía la funcionalidad de <Branch> al manejar automáticamente la pluralización y la concordancia numérica. Utiliza el valor de n proporcionado para determinar qué forma plural mostrar, según las reglas específicas del idioma.

Por ejemplo, el componente <Plural> es ideal para renderizar texto en singular y plural de forma dinámica, como "1 artículo" frente a "2 artículos".

Los componentes de plural suelen combinarse 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 antes de traducirlo.

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

Cuando se usan de forma independiente, simplemente renderizan el contenido tal como está, sin traducirlo.

Cómo usar componentes de rama

Lógica de ramificación con <Branch>

El componente <Branch> se utiliza para cambiar el contenido de manera flexible según un valor de branch.

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

Además, puedes usar otros componentes de 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 la API para más detalles.

Pluralización con <Plural>

El componente <Plural> automatiza la lógica de pluralización según 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 de Unicode CLDR.

Consulta la Referencia de la API para más detalles.

Cuándo usar componentes de rama

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

Cuando necesites mostrar contenido diferente según 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 la 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-next';

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

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

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> mostrará el contenido de los hijos de reserva. Asegúrate siempre de que las posibles claves de rama coincidan con los valores pasados a la prop branch.

import { Branch } from 'gt-next';

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 reserva “Status unknown.”.

Formas Plurales Faltantes

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

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

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

<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 la API para más detalles.
• Aprende más sobre las reglas de pluralización y la lógica de ramificación en Reglas de Pluralización de Unicode CLDR.
• Explora cómo usar Componentes de Variable.