TanStack Start v1에서 통화 정보를 표시하는 방법

문제

애플리케이션은 형식화된 가격을 표시하지 않고도 통화 정보를 표시해야 하는 경우가 많습니다. 통화 선택기는 사용 가능한 통화를 나열하고, 환율에 관한 문서는 기호로 특정 통화를 참조하며, 금융 대시보드는 통화 코드를 표시할 수 있습니다. 그러나 각 표현 방식에는 한계가 있습니다. "USD"와 같은 ISO 코드는 정확하지만 비기술 사용자에게는 난해합니다. "US Dollar"와 같은 전체 이름은 명확하지만 국제 사용자를 위해 번역이 필요합니다. "$"와 같은 기호는 친숙하지만 모호합니다. 동일한 기호가 미국, 캐나다 및 호주 달러를 나타냅니다. 컨텍스트에 맞지 않는 형식을 선택하면 명확성이 떨어지고 사용자에게 혼란을 줄 수 있습니다.

이 문제는 현지화로 인해 더욱 복잡해집니다. 영어로는 작동하는 통화 이름이 다른 언어에서는 존재하지 않거나 올바르지 않을 수 있습니다. 한 지역에서 표준인 기호가 다른 지역에서는 낯설 수 있습니다. 일관되고 로케일을 인식하는 접근 방식이 없으면 애플리케이션은 단일 언어로 통화 표현을 하드코딩하거나 빠르게 구식이 되는 대규모 번역 테이블을 유지 관리해야 합니다.

해결 방법

브라우저의 내장 국제화 API를 사용하여 사용자의 로케일과 컨텍스트에 맞는 형식으로 통화 정보를 표시하세요. Intl.DisplayNames API는 현지화된 전체 통화 이름을 제공하며, currencyDisplay 옵션을 사용하는 Intl.NumberFormat는 통화 기호나 코드를 추출할 수 있습니다. 컨텍스트에 따라 적절한 API와 형식 옵션을 선택하면 번역 데이터를 유지 관리하지 않고도 통화 참조가 명확하고 적절하게 현지화됩니다.

통화 코드와 로케일을 받아들인 다음 적절한 표현을 반환하는 작고 재사용 가능한 컴포넌트 또는 헬퍼 함수를 만듭니다. 이 접근 방식은 통화 표시 로직을 중앙 집중화하고 애플리케이션 전체에서 동일한 통화를 다양한 형식으로 쉽게 표시할 수 있도록 합니다.

단계

1. 현지화된 통화 이름을 가져오는 헬퍼 생성

type: "currency"를 사용하는 Intl.DisplayNames API는 모든 ISO 4217 통화 코드에 대해 현지화된 전체 통화 이름을 반환합니다.

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

이 헬퍼는 세 글자 ISO 통화 코드를 받아 사용자의 언어로 전체 이름을 반환합니다. 간결함보다 명확성이 더 중요한 통화 선택기나 설명 텍스트에 사용하세요.

2. 통화 기호를 추출하는 헬퍼 생성

Intl.NumberFormat의 currencyDisplay 옵션은 통화 표시 방식을 제어하며, "code", "symbol", "narrowSymbol", "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;
}

이 헬퍼는 0 값을 포맷하고 통화 기호만 추출합니다. narrow 매개변수는 "$"와 같은 간결한 기호를 사용할지 "US$"와 같은 명확한 기호를 사용할지 제어합니다. 테이블이나 차트와 같은 간결한 UI 요소에서는 기호를 사용하세요.

3. 통화 정보를 표시하는 컴포넌트 생성

display prop을 기반으로 모든 형식의 통화 정보를 렌더링할 수 있는 유연한 컴포넌트를 구축하세요.

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>;
}

이 컴포넌트는 통화 표시 로직을 중앙 집중화하고 형식 전환을 쉽게 만듭니다. 드롭다운 및 설명 텍스트에는 "name"을 사용하고, 간결한 표시에는 "symbol" 또는 "narrowSymbol"를 사용하며, 정확성이 필요한 경우 "code"를 사용하세요.

4. TanStack Start 라우트에서 컴포넌트 사용

i18n 컨텍스트나 라우트 로더에서 사용자의 로케일을 전달하여 모든 라우트 컴포넌트에서 컴포넌트를 가져와 사용합니다.

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>
  );
}

컴포넌트는 동일한 통화를 다양한 형식으로 렌더링합니다. 실제 애플리케이션에서는 i18n 프로바이더나 라우트 컨텍스트에서 로케일을 가져와 모든 통화 표시가 사용자의 언어 기본 설정을 준수하도록 합니다.