Comment formater les nombres pour différentes locales dans TanStack Start v1

Problème

Les nombres s'écrivent différemment à travers le monde. Ce qui apparaît comme 10,000.5 aux États-Unis devient 10.000,5 en Allemagne—les virgules et les points échangent complètement leurs rôles. Ce n'est pas une question de préférence ou de style, mais de lisibilité. Un utilisateur allemand voyant 10,000.5 pourrait le lire comme dix, ignorant les séparateurs de groupement. Un utilisateur américain voyant 10.000,5 pourrait le lire comme dix mille, ignorant le séparateur décimal. Les mêmes chiffres, des significations opposées.

Lorsque les applications affichent des nombres sans tenir compte des conventions de formatage régionales, elles créent de la confusion et érodent la confiance. Les utilisateurs s'attendent à ce que les nombres suivent les modèles qu'ils ont appris, et les écarts par rapport à ces modèles les forcent à s'arrêter, à réinterpréter et à se demander si les données sont correctes.

Solution

Formatez les nombres en fonction de la locale de l'utilisateur, en utilisant les règles régionales pour les séparateurs décimaux et de groupement. Cela transforme les valeurs numériques en chaînes qui suivent les règles de formatage familières aux utilisateurs dans leur région.

React-intl fournit des composants et des hooks qui exploitent l'API intégrée du navigateur Intl.NumberFormat pour appliquer un formatage spécifique à la locale. En passant une valeur numérique et la locale actuelle, ces outils sélectionnent automatiquement les séparateurs corrects, le regroupement des chiffres et d'autres conventions régionales. Le résultat est une chaîne formatée qui correspond aux attentes des utilisateurs sans manipulation manuelle de chaîne ou logique spécifique à la locale dans vos composants.

Étapes

1. Créer un composant d'affichage de nombre en utilisant FormattedNumber

Construisez un composant qui accepte une valeur numérique et la rend avec un formatage approprié à la locale en utilisant le composant FormattedNumber de react-intl.

import { FormattedNumber } from "react-intl";

interface PriceDisplayProps {
  value: number;
}

export function PriceDisplay({ value }: PriceDisplayProps) {
  return (
    <div>
      <FormattedNumber value={value} />
    </div>
  );
}

Le composant FormattedNumber applique automatiquement les séparateurs décimaux et de groupement de la locale. Il lit la locale depuis le IntlProvider le plus proche dans l'arborescence des composants et formate le nombre en conséquence.

2. Formater les nombres avec des styles spécifiques

Personnalisez le formatage des nombres en passant des options de style à FormattedNumber pour les devises, les pourcentages ou les unités.

import { FormattedNumber } from "react-intl";

interface MetricsProps {
  revenue: number;
  growthRate: number;
  fileSize: number;
}

export function Metrics({ revenue, growthRate, fileSize }: MetricsProps) {
  return (
    <div>
      <p>
        Revenu:{" "}
        <FormattedNumber value={revenue} style="currency" currency="USD" />
      </p>
      <p>
        Croissance: <FormattedNumber value={growthRate} style="percent" />
      </p>
      <p>
        Taille:{" "}
        <FormattedNumber
          value={fileSize}
          style="unit"
          unit="megabyte"
          unitDisplay="short"
        />
      </p>
    </div>
  );
}

La prop style contrôle le mode de formatage. Le formatage des devises nécessite un code currency, le formatage des pourcentages multiplie automatiquement par 100, et le formatage des unités nécessite un identifiant unit. Tous les styles respectent les conventions de la locale active.

3. Formater les nombres de manière impérative avec useIntl

Utilisez le hook useIntl pour formater les nombres dans des contextes où les composants ne sont pas adaptés, comme la génération d'attributs dynamiques ou la préparation de données pour des API non-React.

import { useIntl } from "react-intl";

interface ChartTooltipProps {
  dataPoint: number;
}

export function ChartTooltip({ dataPoint }: ChartTooltipProps) {
  const intl = useIntl();
  const formattedValue = intl.formatNumber(dataPoint, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  });

  return <div title={formattedValue}>{formattedValue}</div>;
}

La méthode formatNumber renvoie immédiatement une chaîne formatée, ce qui la rend adaptée aux attributs, aux labels aria, ou à tout contexte où vous avez besoin de la valeur formatée sous forme de chaîne plutôt que d'élément React.

4. Appliquer des options de formatage personnalisées

Contrôlez la précision, le regroupement et la notation en passant Intl.NumberFormatOptions à FormattedNumber ou à formatNumber.

import { FormattedNumber } from "react-intl";

interface StatisticProps {
  value: number;
  compact?: boolean;
}

export function Statistic({ value, compact }: StatisticProps) {
  return (
    <div>
      <FormattedNumber
        value={value}
        notation={compact ? "compact" : "standard"}
        minimumFractionDigits={0}
        maximumFractionDigits={2}
      />
    </div>
  );
}

Les options comme notation, minimumFractionDigits et maximumFractionDigits contrôlent l'affichage du nombre. La notation compacte convertit les grands nombres en formes abrégées comme "1,2 M" tout en respectant les abréviations spécifiques à la locale.