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

Problema

Las aplicaciones a menudo necesitan mostrar información de monedas sin mostrar un precio formateado. Un selector de monedas podría listar las monedas disponibles, un artículo sobre tipos de cambio podría hacer referencia a monedas específicas por su símbolo, o un panel financiero podría mostrar códigos de monedas. 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 consciente de la configuración regional, las aplicaciones codifican de forma rígida las representaciones de monedas en un solo idioma o mantienen grandes tablas de traducción que rápidamente quedan obsoletas.

Solución

Utiliza las API de internacionalización integradas del navegador para mostrar información de monedas 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 monedas localizados, mientras que Intl.NumberFormat con la opción currencyDisplay puede extraer símbolos o códigos de monedas. Al seleccionar la API y la opción de formato apropiadas según el contexto, te aseguras de que las referencias de monedas sean claras y estén correctamente localizadas sin 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 monedas centralizada y facilita mostrar la misma moneda en diferentes formatos en toda tu aplicación.

Pasos

1. Crear un helper para obtener nombres de divisas localizados

La API Intl.DisplayNames con type: "currency" devuelve nombres completos de divisas localizados para cualquier código de divisa 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 divisa ISO de tres letras y devuelve el nombre completo en el idioma del usuario. Úsalo para selectores de divisas o texto explicativo donde la claridad es más importante que la brevedad.

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

La opción currencyDisplay en Intl.NumberFormat controla cómo aparece la divisa, 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 únicamente el símbolo de la divisa. El parámetro narrow controla si usar un símbolo compacto como "$" o uno desambiguado como "US$". Usa símbolos en elementos de interfaz compactos como tablas o gráficos.

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

Construye un componente flexible que pueda renderizar información de divisas en cualquier formato basándose 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 divisas y facilita el cambio de formatos. Usa "name" para menús desplegables y texto explicativo, "symbol" o "narrowSymbol" para visualizaciones compactas, y "code" cuando se requiere precisión.

4. Usar 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 divisa 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 divisas respeten la preferencia de idioma del usuario.