Utilisation des variables

Aperçu

Les composants variables dans gt-next vous permettent d'insérer du contenu dynamique dans les traductions. Ces composants incluent :

• <Var> : Pour afficher des variables.
• <Num> : Pour formater des nombres.
• <Currency> : Pour formater des valeurs monétaires.
• <DateTime> : Pour formater des dates et des heures.

Dans ce guide, nous aborderons :

Que sont les composants variables ?

Les composants variables sont utilisés pour encapsuler du contenu dynamique tel que des noms d'utilisateur, des valeurs numériques, des dates et des devises.

Ces composants vous permettent de formater et d'afficher des valeurs dynamiques d'une manière adaptée à la langue et à la région de l'utilisateur, sans nécessiter de traductions externes.

Utilisez les composants variables en combinaison avec le composant <T> afin de garantir que le contenu dynamique soit affiché de manière précise et cohérente.

Chaque composant variable a un comportement différent :

• <Var> : Affiche dynamiquement tout type de contenu, comme des noms d'utilisateur ou des identifiants.
• <Num> : Formate les valeurs numériques selon les règles spécifiques à la langue et à la région.
• <Currency> : Formate les valeurs monétaires avec les symboles et règles de localisation appropriés.
• <DateTime> : Formate les dates et heures en utilisant les conventions propres à la langue et à la région.

Alors que le contenu JSX et les chaînes de caractères sont traduits via l'API de traduction générale, les composants variables sont entièrement gérés localement.

Les composants <Num>, <Currency> et <DateTime> utilisent l'API JS i18n pour formater le contenu selon la langue et la région de l'utilisateur.

Comment utiliser les composants de variables

Utilisation de base

L'utilisation est la même pour tous les composants de variables.

const user = {
  name: 'John',
  age: 30,
  balance: 1000,
  birthday: new Date('1990-01-01'),
}
<div>
  <Var>{user.name}</Var>
  <Num>{user.age}</Num>
  <Currency>{user.balance}</Currency>
  <DateTime>{user.birthday}</DateTime>
</div>

Il suffit d'envelopper le composant de variable autour du contenu que vous souhaitez afficher.

Utilisation des composants de variables dans <T>

Par eux-mêmes, les composants de variables ne font pas grand-chose, car ils nécessitent la connaissance de la locale de l'utilisateur pour formater le contenu.

Ainsi, vous devriez utiliser les composants de variables avec les composants <T>.

Le composant <T> gérera non seulement la traduction du contenu environnant, mais transmettra également la locale correcte à ses composants de variables enfants.

<T>
  L'heure actuelle est <DateTime>{time}</DateTime>.
</T>

Localisation des variables

Les composants <Num>, <Currency>, et <DateTime> incluent un support de localisation intégré. Ces composants formatent automatiquement leur contenu en fonction de la locale sélectionnée par votre utilisateur, ou en fonction d'options supplémentaires passées comme props.

Par exemple :

• <Num> affiche les nombres avec des séparateurs décimaux localisés.
• <Currency> affiche les valeurs avec des symboles de devise localisés et un positionnement approprié.
• <DateTime> affiche les dates et heures selon les règles spécifiques à la locale.

Vous pouvez également remplacer la locale par défaut et les options de formatage en passant des props directement à ces composants.

Confidentialité des données

Les composants de variables gèrent tout le formatage localement ; par conséquent, aucun de leurs enfants n'est envoyé aux APIs General Translation pour traduction (lorsqu'ils sont utilisés avec les composants <T>). C'est parfait pour garder les données sensibles, telles que les noms d'utilisateur ou les numéros de compte, privées et sécurisées.

Chaque composant de variable gère le formatage différemment et devrait être utilisé pour des types spécifiques de contenu :

• <Var> : Tout ce qui est privé et ne nécessite pas de formatage
  • Noms d'utilisateur, numéros de compte, etc.
• <Num> : Valeurs numériques privées qui devraient être formatées selon la locale
  • Quantités de commande, âge, distance, etc.
• <Currency> : Valeurs monétaires privées qui devraient être formatées selon la locale
  • Montants de transaction, soldes de compte, etc.
• <DateTime> : Valeurs de date et heure privées qui devraient être formatées selon la locale
  • Dates de création de compte, horodatages de commande, etc.

<T>
  <Var>
    <T>Hello, world!</T>
    Goodbye, World!
  </Var>
</T>

Exemples

<Var>

Comme le composant <Var> n’effectue aucun formatage, il doit toujours être utilisé en conjonction avec un composant <T>.

import { T, Var } from 'gt-next';

export default function UserGreeting({ user }) {
  return (
    <T>
      Hello, <Var>{user.name}</Var>!
      Your address is <Var>{user.addr}</Var>
    </T>
  );
}

Les composants de variable isolent également les données, ils peuvent donc être utilisés pour afficher du contenu dynamique qui ne fait pas partie d’une traduction.

import { T, Var } from 'gt-next';

export default function Dashboard({ isAdmin }) {
  return (
    <T>
      Your Dashboard:
      <Var>{isAdmin ? <AdminDashboard /> : <UserDashboard />}</Var>
    </T>
  );
}

Dans l’exemple ci-dessus, l’opérateur ternaire isAdmin rend le composant Dashboard dynamique.

Sans le composant <Var>, ceci serait une utilisation invalide du composant <T>.

<Num>

Le composant <Num> peut être utilisé comme enfant d’un composant <T> ou comme composant autonome.

import { T, Num } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';

export default function OrderSummary() {
  const quantity = 10;
  return (
    <>
      <T>
        You have <Num>{quantity}</Num> items in your cart.
      </T>
      <Badge>
        <Num>{quantity}</Num> // This is the same as using quantity.toLocaleString()
      </Badge>
    </>
  );
}

<Currency>

Le composant <Currency> peut être utilisé comme enfant d’un composant <T> ou comme composant autonome.

import { T, Currency } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';

export default function OrderSummary() {
  const total = 1000;
  return (
    <>
      <T>
        Your total is <Currency currency={"USD"}>{total}</Currency>.
      </T>
      <Badge>
        <Currency currency={"USD"}>{total}</Currency> // This will be formatted as $1,000
      </Badge>
    </>
  );
}

<DateTime>

Le composant <DateTime> peut être utilisé comme enfant d’un composant <T> ou comme composant autonome.

import { T, DateTime } from 'gt-next';

export default function OrderSummary() {
  const date = new Date();
  return (
    <T>
      Your order was placed on <DateTime>{date}</DateTime>.
    </T>
    <DateTime>{date}</DateTime> // This is the same as using date.toLocaleDateString() or date.toLocaleTimeString()
  );
}

Pièges courants

Ignorer les options de localisation

Pour <Currency>, assurez-vous de passer la prop currency afin de spécifier le type de devise. Cela garantit que le symbole monétaire et le formatage corrects sont utilisés lors de l'affichage de la valeur.

D'autres composants, comme <Num> et <DateTime>, disposent également de props optionnelles qui vous permettent de personnaliser le formatage.

Notes

• Les composants de variable isolent les données, ils peuvent donc être utilisés pour afficher du contenu dynamique qui ne fait pas partie d'une traduction.
• Les composants de variable n'envoient pas de données aux API de traduction générale, ils sont donc parfaits pour garder les données sensibles privées et sécurisées.
• Les composants de variable peuvent être utilisés soit comme enfant d'un composant <T>, soit comme composant autonome.

Prochaines étapes

• Explorez la logique conditionnelle dans Branching Components.
• Découvrez-en plus sur les options de formatage pour des composants de variable spécifiques dans la Référence API :
  • <Num>
  • <Currency>
  • <DateTime>
  • <Var>