Cómo formatear números para diferentes configuraciones regionales en TanStack Start v1

Problema

Los números se escriben de manera diferente en todo el mundo. Lo que aparece como 10,000.5 en Estados Unidos se convierte en 10.000,5 en Alemania: las comas y los puntos intercambian completamente sus funciones. Esto no es una cuestión de preferencia o estilo, sino de legibilidad. Un usuario alemán que vea 10,000.5 podría leerlo como diez, ignorando los separadores de agrupación. Un usuario estadounidense que vea 10.000,5 podría leerlo como diez mil, ignorando el separador decimal. Los mismos dígitos, significados opuestos.

Cuando las aplicaciones muestran números sin considerar las convenciones de formato regionales, crean confusión y erosionan la confianza. Los usuarios esperan que los números sigan los patrones que aprendieron, y las desviaciones de esos patrones los obligan a detenerse, reinterpretar y cuestionar si los datos son correctos.

Solución

Formatea los números según la configuración regional del usuario, utilizando reglas regionales para los separadores decimales y de agrupación. Esto convierte los valores numéricos en cadenas que siguen las reglas de formato familiares para los usuarios de su región.

React-intl proporciona componentes y hooks que aprovechan la API Intl.NumberFormat integrada del navegador para aplicar formato específico de cada región. Al pasar un valor numérico y la configuración regional actual, estas herramientas seleccionan automáticamente los separadores correctos, la agrupación de dígitos y otras convenciones regionales. El resultado es una cadena formateada que coincide con las expectativas del usuario sin manipulación manual de cadenas ni lógica específica de configuración regional en tus componentes.

Pasos

1. Crea un componente de visualización de números usando FormattedNumber

Construye un componente que acepte un valor numérico y lo renderice con formato apropiado para la configuración regional usando el componente FormattedNumber de react-intl.

import { FormattedNumber } from "react-intl";

interface PriceDisplayProps {
  value: number;
}

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

El componente FormattedNumber aplica automáticamente los separadores decimales y de agrupación de la configuración regional. Lee la configuración regional del IntlProvider más cercano en el árbol de componentes y formatea el número en consecuencia.

2. Formatear números con estilos específicos

Personaliza el formato de números pasando opciones de estilo a FormattedNumber para moneda, porcentajes o unidades.

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 controla el modo de formato. El formato de moneda requiere un código currency, el formato de porcentaje multiplica automáticamente por 100, y el formato de unidad requiere un identificador unit. Todos los estilos respetan las convenciones de la configuración regional activa.

3. Formatear números imperativamente con useIntl

Usa el hook useIntl para formatear números en contextos donde los componentes no son adecuados, como generar atributos dinámicos o preparar datos para APIs que no son de 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>;
}

El método formatNumber devuelve una cadena formateada inmediatamente, lo que lo hace adecuado para atributos, etiquetas aria o cualquier contexto donde necesites el valor formateado como cadena en lugar de un elemento React.

4. Aplicar opciones de formato personalizadas

Controla la precisión, agrupación y notación pasando Intl.NumberFormatOptions a FormattedNumber o 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>
  );
}

Opciones como notation, minimumFractionDigits y maximumFractionDigits controlan cómo se muestra el número. La notación compacta convierte números grandes en formas abreviadas como "1,2 M" respetando las abreviaturas específicas de cada configuración regional.