Utilisation des branches

Aperçu

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

• <Branch> : Affiche du contenu en fonction d'une correspondance avec la prop branch.
• <Plural> : Affiche du contenu en fonction des règles de pluralisation pour un nombre donné.

Les deux composants fournissent 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 children de secours est affiché.

Par exemple, le composant <Branch> est parfait pour l'affichage 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 les fonctionnalités de <Branch> en gérant automatiquement la pluralisation et l'accord en nombre. Il utilise la valeur n fournie pour déterminer quelle forme plurielle afficher, selon les règles spécifiques à la locale.

Par exemple, le composant <Plural> est idéal pour afficher dynamiquement du texte au singulier et au pluriel, comme "1 élément" contre "2 éléments".

Les composants Plural sont souvent combinés avec des composants <Num> pour localiser un nombre et son texte correspondant.

Utilisation avec <T>

Les composants <Branch> et <Plural> doivent être utilisés au sein d'un composant <T> pour assainir le contenu dynamique pour la traduction.

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

Lorsqu'ils sont utilisés seuls, ils afficheront 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 une commutation flexible du contenu basée 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 variables 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.

Consultez la Référence API pour plus de détails.

Pluralisation avec <Plural>

Le composant <Plural> automatise la logique de pluralisation basée sur la valeur de n. Le composant choisit dynamiquement la forme plurielle appropriée pour le nombre et la locale 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 locale et suivent les règles de pluralisation CLDR Unicode.

Consultez 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 différents contenus 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;
// 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 vous souhaitez rendre du contenu avec une pluralisation correcte, utilisez <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>}

Exemples

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

Dans l'exemple ci-dessus, le composant <Branch> change 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 par défaut :

<p>Status unknown.</p>

Comme le composant <Branch> est enveloppé dans un composant <T>, le contenu rendu est automatiquement traduit dans son contexte.

Dans cet exemple, il affiche différentes descriptions en fonction du forfait d'abonnement de l'utilisateur.

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 détermine quel message de forfait afficher.
• Si plan est "free", "premium", ou "enterprise", le message correspondant est affiché.
• Si plan ne correspond à aucune de ces valeurs, le contenu par défaut ("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-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 spécifie le nombre de messages non lus.
• Si unreadCount est 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>.

Erreurs courantes

Valeurs de branche manquantes

Si une valeur de branche n'est pas fournie ou ne correspond à aucune clé, le composant <Branch> affichera le contenu de secours des enfants. Assurez-vous toujours que les clés de branche possibles correspondent aux valeurs transmises à 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 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-react s'assure que votre application dispose toujours d'un contenu de secours à afficher.

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

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

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

Alternativement, 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 à chaque langue.
• Incluez toujours une prop children de secours pour une meilleure gestion des erreurs et une meilleure expérience utilisateur.

Prochaines étapes

• Consultez <Branch> et <Plural> dans la référence API pour plus de détails.
• Apprenez-en davantage sur les règles de pluralisation et la logique de branchement dans les Règles de pluralisation Unicode CLDR.
• Explorez comment utiliser les Composants variables.