Utilisation des branches

Aperçu

Les composants de branchement dans gt-next permettent un rendu dynamique du contenu basé sur des conditions spécifiques. Ces composants incluent :

• <Branch> : Affiche le contenu en fonction d'une prop branch correspondante.
• <Plural> : Affiche le contenu selon les règles de pluralisation pour un nombre donné.

Les deux composants offrent des outils puissants pour gérer la logique conditionnelle et le contenu dynamique dans les applications localisées.

Dans ce guide, nous aborderons :

Que sont les composants de branche ?

Les composants de branche choisissent dynamiquement quel contenu afficher en fonction d'une condition ou d'une valeur spécifique.

<Branch>

Le composant <Branch> vous permet d'afficher différents contenus en fonction d'une valeur branch fournie. Si aucune branche correspondante n'est trouvée, le contenu de repli children est affiché.

Par exemple, le composant <Branch> est parfait pour le rendu conditionnel basé sur l'état de l'application, les préférences de l'utilisateur ou toute donnée dynamique.

Le cas d'utilisation le plus courant est de l'utiliser pour remplacer un opérateur ternaire ou conditionnel.

<Plural>

Le composant <Plural> étend la fonctionnalité de <Branch> en gérant automatiquement la pluralisation et l'accord des nombres. Il utilise la valeur n fournie pour déterminer quelle forme plurielle afficher, selon les règles spécifiques à la langue.

Par exemple, le composant <Plural> est idéal pour afficher dynamiquement du texte au singulier ou au pluriel, comme "1 article" contre "2 articles".

Les composants pluriels sont souvent combinés avec les composants <Num> pour localiser un nombre et son texte associé.

Utilisation avec <T>

Les composants <Branch> et <Plural> doivent être utilisés à l'intérieur d'un composant <T> pour assainir le contenu dynamique destiné à la traduction.

Lorsqu'ils sont utilisés à l'intérieur d'un composant <T>, le contenu est automatiquement traduit et affiché dans la langue sélectionnée par l'utilisateur.

Lorsqu'ils sont utilisés seuls, ils affichent simplement le contenu tel quel, sans le traduire.

Comment utiliser les composants de branche

Logique de branchement avec <Branch>

Le composant <Branch> est utilisé pour un changement de contenu flexible basé sur une valeur branch.

Vous pouvez définir plusieurs branches possibles, et le composant affichera le contenu correspondant à la clé de branche correspondante.

De plus, vous pouvez utiliser d'autres composants de variable en combinaison avec le composant <Branch>.

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

Le composant <Branch> doit être utilisé à l'intérieur d'un composant <T>. Cela permet au contenu d'être automatiquement traduit.

Voir la référence API pour plus de détails.

Pluralisation avec <Plural>

Le composant <Plural> automatise la logique de pluralisation en fonction de la valeur de n. Le composant choisit dynamiquement la forme plurielle appropriée pour le nombre et la langue donnés.

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>

Les formes plurielles disponibles dépendent de la langue et suivent les règles de pluralisation Unicode CLDR.

Voir la référence API pour plus de détails.

Quand utiliser les composants de branche

Les composants de branche sont importants pour gérer le contenu dynamique dans votre application.

Lorsque vous devez afficher un contenu différent en fonction d'une condition, utilisez <Branch>.

Ces conditions peuvent être basées sur un composant variable, un booléen ou une fonction.

Par exemple, si votre code utilise un opérateur ternaire ou un rendu conditionnel, vous pouvez utiliser <Branch> pour le remplacer.

const isActive = true;
// Opérateur ternaire
<Branch branch={isActive} true={<p>L'utilisateur est actif.</p>} false={<p>L'utilisateur est inactif.</p>}>
  <p>Statut inconnu.</p>
</Branch>

// Rendu conditionnel
<Branch branch={isActive} true={<p>L'utilisateur est actif.</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 vous souhaitez afficher un contenu avec la bonne pluralisation, utilisez <Plural>.

const count = 1;
<Plural n={count} one={<p>1 élément</p>} other={<p>{count} éléments</p>} />

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

Exemples

<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>
  );
}

Dans l'exemple ci-dessus, le composant <Branch> bascule dynamiquement entre 3 contenus rendus en fonction de la valeur de status.

Lorsque status est "active", le composant affiche :

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

Lorsque status est "inactive", le composant affiche :

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

Lorsque status n'est ni "active" ni "inactive", le composant affiche le contenu de secours :

<p>Status unknown.</p>

Puisque le composant <Branch> est enveloppé dans un composant <T>, le contenu affiché est automatiquement traduit dans le contexte.

Dans cet exemple, il affiche différentes descriptions selon le forfait d'abonnement de l'utilisateur.

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 détermine quel message de forfait afficher.
• Si plan vaut "free", "premium" ou "enterprise", le message correspondant est affiché.
• Si plan ne correspond à aucune de ces valeurs, le contenu de secours ("No subscription plan detected.") est affiché.

<Plural>

Le composant <Plural> gère dynamiquement le contenu singulier et pluriel en fonction de la valeur de n. Cet exemple affiche le nombre de messages non lus dans la boîte de réception d'un utilisateur.

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 indique le nombre de messages non lus.
• Si unreadCount vaut 1, le composant affiche : "You have 1 unread message."
• Pour toute autre valeur, il affiche : "You have X unread messages." où X est la valeur de unreadCount formatée par <Num>.

Pièges courants

Valeurs de branche manquantes

Si une valeur de branche n'est pas fournie ou ne correspond à aucune clé, le composant <Branch> affichera le contenu enfant de secours. Assurez-vous toujours que les clés de branche possibles correspondent aux valeurs passées à 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 est undefined ou une valeur autre que active ou inactive, le contenu de secours “Status unknown.” sera affiché.

Formes plurielles manquantes

N'oubliez pas de spécifier toutes les formes plurielles nécessaires dans votre langue par défaut. C'est ainsi que gt-next garantit que votre application dispose toujours d'un contenu de secours à afficher.

Par exemple, si l'anglais est votre langue par défaut, vous devez fournir toutes les formes plurielles pour l'anglais.

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.</>}
/>

Ici, nous avons fourni les formes plurielles one et other pour l'anglais.

Vous pouvez également fournir singular et plural pour l'anglais.

Notes

• Les composants Branch sont essentiels pour gérer du contenu dynamique et localisé dans les applications.
• Le composant <Branch> est très flexible et peut s'adapter à diverses conditions et états.
• Le composant <Plural> simplifie la pluralisation en respectant automatiquement les règles spécifiques à la langue.
• Incluez toujours une prop children de secours pour une meilleure gestion des erreurs et une expérience utilisateur optimale.

Prochaines étapes

• Consultez <Branch> et <Plural> dans la Référence API pour plus de détails.
• Découvrez-en plus sur les règles de pluralisation et la logique de branchement dans Unicode CLDR Pluralization Rules.
• Explorez comment utiliser les Variable Components.