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

문제

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

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

해결책

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

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

단계

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

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

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>통화 정보</h1>
      <p>
        전체 이름: <CurrencyDisplay code="USD" locale={locale} display="name" />
      </p>
      <p>
        기호: <CurrencyDisplay code="USD" locale={locale} display="symbol" />
      </p>
      <p>
        코드: <CurrencyDisplay code="USD" locale={locale} display="code" />
      </p>
    </div>
  );
}

이 컴포넌트는 동일한 통화를 다양한 형식으로 렌더링합니다. 실제 애플리케이션에서는 모든 통화 표시가 사용자의 언어 환경을 존중하도록 i18n 제공자나 라우트 컨텍스트에서 로케일을 가져오세요.