Cómo mostrar información de moneda en TanStack Start v1

Problema

Las aplicaciones a menudo necesitan mostrar información de divisas sin mostrar un precio formateado. Un selector de divisas podría enumerar las monedas disponibles, un artículo sobre tipos de cambio podría hacer referencia a divisas específicas por su símbolo, o un panel financiero podría mostrar códigos de moneda. Sin embargo, cada representación tiene limitaciones. Los códigos ISO como "USD" son precisos pero crípticos para usuarios no técnicos. Los nombres completos como "Dólar estadounidense" son claros pero requieren traducción para audiencias internacionales. Los símbolos como "$" son familiares pero ambiguos—el mismo símbolo representa dólares estadounidenses, canadienses y australianos. Elegir el formato incorrecto para el contexto reduce la claridad y puede confundir a los usuarios.

El desafío se complica con la localización. Un nombre de moneda que funciona en inglés puede no existir o ser incorrecto en otro idioma. Los símbolos que son estándar en una región pueden ser desconocidos en otra. Sin un enfoque consistente y adaptado a la configuración regional, las aplicaciones codifican representaciones de divisas en un solo idioma o mantienen grandes tablas de traducción que rápidamente quedan obsoletas.

Solución

Utiliza las APIs de internacionalización integradas en el navegador para mostrar información de divisas en el formato que coincida tanto con la configuración regional del usuario como con el contexto. La API Intl.DisplayNames proporciona nombres completos de divisas localizados, mientras que Intl.NumberFormat con la opción currencyDisplay puede extraer símbolos o códigos de moneda. Al seleccionar la API y la opción de formato apropiadas según el contexto, aseguras que las referencias a divisas sean claras y estén correctamente localizadas sin necesidad de mantener datos de traducción.

Crea componentes pequeños y reutilizables o funciones auxiliares que acepten un código de moneda y una configuración regional, y luego devuelvan la representación apropiada. Este enfoque mantiene la lógica de visualización de divisas centralizada y facilita mostrar la misma moneda en diferentes formatos en toda tu aplicación.

Pasos

1. Crear un helper para obtener nombres de monedas localizados

La API Intl.DisplayNames con type: "currency" devuelve nombres completos de monedas localizados para cualquier código de moneda ISO 4217.

export function getCurrencyName(currencyCode: string, locale: string): string {
  const displayNames = new Intl.DisplayNames([locale], { type: "currency" });
  return displayNames.of(currencyCode) || currencyCode;
}

Este helper acepta un código de moneda ISO de tres letras y devuelve el nombre completo en el idioma del usuario. Úsalo para selectores de moneda o texto explicativo donde la claridad es más importante que la brevedad.

2. Crear un helper para extraer símbolos de moneda

La opción currencyDisplay en Intl.NumberFormat controla cómo aparece la moneda, con valores "code", "symbol", "narrowSymbol" y "name".

export function getCurrencySymbol(
  currencyCode: string,
  locale: string,
  narrow: boolean = false,
): string {
  const formatter = new Intl.NumberFormat(locale, {
    style: "currency",
    currency: currencyCode,
    currencyDisplay: narrow ? "narrowSymbol" : "symbol",
  });

  const parts = formatter.formatToParts(0);
  const currencyPart = parts.find((part) => part.type === "currency");
  return currencyPart?.value || currencyCode;
}

Este helper formatea un valor cero y extrae solo el símbolo de la moneda. El parámetro narrow controla si se usa un símbolo compacto como "$" o uno desambiguado como "US$". Usa símbolos en elementos de UI compactos como tablas o gráficos.

3. Crear un componente para mostrar información de moneda

Construye un componente flexible que pueda renderizar información de moneda en cualquier formato basado en una prop display.

interface CurrencyDisplayProps {
  code: string;
  locale: string;
  display: "name" | "symbol" | "narrowSymbol" | "code";
}

export function CurrencyDisplay({
  code,
  locale,
  display,
}: CurrencyDisplayProps) {
  let content: string;

  if (display === "name") {
    content = getCurrencyName(code, locale);
  } else if (display === "code") {
    content = code.toUpperCase();
  } else {
    content = getCurrencySymbol(code, locale, display === "narrowSymbol");
  }

  return <span>{content}</span>;
}

Este componente centraliza la lógica de visualización de moneda y facilita el cambio de formatos. Usa "name" para desplegables y texto explicativo, "symbol" o "narrowSymbol" para visualizaciones compactas, y "code" cuando se requiere precisión.

4. Usa el componente en una ruta de TanStack Start

Importa y usa el componente en cualquier componente de ruta, pasando la configuración regional del usuario desde tu contexto i18n o cargador de ruta.

import { createFileRoute } from "@tanstack/react-router";
import { CurrencyDisplay } from "~/components/CurrencyDisplay";

export const Route = createFileRoute("/currencies")({
  component: CurrenciesPage,
});

function CurrenciesPage() {
  const locale = "en-US";

  return (
    <div>
      <h1>Currency Information</h1>
      <p>
        Full name: <CurrencyDisplay code="USD" locale={locale} display="name" />
      </p>
      <p>
        Symbol: <CurrencyDisplay code="USD" locale={locale} display="symbol" />
      </p>
      <p>
        Code: <CurrencyDisplay code="USD" locale={locale} display="code" />
      </p>
    </div>
  );
}

El componente renderiza la misma moneda en diferentes formatos. En una aplicación real, obtén la configuración regional desde tu proveedor i18n o contexto de ruta para asegurar que todas las visualizaciones de moneda respeten las preferencias de idioma del usuario.