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. Il ne s'agit pas d'une question de préférence ou de style, mais de lisibilité. Un utilisateur allemand voyant 10,000.5 pourrait le lire comme dix, en ignorant les séparateurs de groupement. Un utilisateur américain voyant 10.000,5 pourrait le lire comme dix mille, en 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 obligent à faire une pause, à réinterpréter et à se demander si les données sont correctes.

Solution

Formater 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 de leur région.

React-intl fournit des composants et des hooks qui exploitent l'API Intl.NumberFormat intégrée au navigateur 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 groupement 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înes ni logique spécifique à la locale dans vos composants.

Étapes

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

Construire 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>
        Revenue:{" "}
        <FormattedNumber value={revenue} style="currency" currency="USD" />
      </p>
      <p>
        Growth: <FormattedNumber value={growthRate} style="percent" />
      </p>
      <p>
        Size:{" "}
        <FormattedNumber
          value={fileSize}
          style="unit"
          unit="megabyte"
          unitDisplay="short"
        />
      </p>
    </div>
  );
}

La prop style contrôle le mode de formatage. Le formatage de devise nécessite un code currency, le formatage de pourcentage multiplie automatiquement par 100, et le formatage d'unité 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 retourne 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 groupement 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 la façon dont le nombre est affiché. 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.