Intl.DisplayNames API - JavaScript i18n

소개

애플리케이션에는 국가 코드 US가 있지만, 사용자에게는 "United States"라는 텍스트가 표시됩니다. 언어 코드 fr가 있지만, 언어 전환기에는 "French"가 표시됩니다. 통화 코드 EUR가 있지만, 결제 페이지에는 "Euro"가 표시됩니다.

브라우저는 다양한 언어로 자체 인터페이스를 렌더링하기 위해 광범위한 로컬라이제이션 데이터를 유지합니다. Intl.DisplayNames API는 이 데이터를 JavaScript에 노출하여 표준화된 코드를 모든 언어로 로컬라이즈된 사람이 읽을 수 있는 이름으로 변환합니다.

이를 통해 유지 관리 및 로컬라이제이션이 필요한 서드파티 라이브러리나 커스텀 조회 테이블이 필요하지 않습니다. 브라우저가 데이터와 번역을 모두 처리합니다.

지역 코드를 국가 이름으로 변환

가장 일반적인 사용 사례는 ISO 국가 코드를 국가 이름으로 변환하는 것입니다. 로케일과 타입으로 DisplayNames 인스턴스를 생성한 다음, 국가 코드로 of() 메서드를 호출합니다:

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States"
console.log(regionNames.of("GB")); // "United Kingdom"
console.log(regionNames.of("JP")); // "Japan"

첫 번째 매개변수는 BCP 47 표준을 따르는 로케일 코드 배열을 허용합니다. 브라우저는 배열에서 지원되는 첫 번째 로케일을 사용합니다. type 옵션은 변환하려는 코드의 종류를 지정합니다.

동일한 코드가 다른 언어로 로컬라이즈될 때 다른 출력을 생성합니다:

const englishRegions = new Intl.DisplayNames(["en"], { type: "region" });
const japaneseRegions = new Intl.DisplayNames(["ja"], { type: "region" });
const spanishRegions = new Intl.DisplayNames(["es"], { type: "region" });

console.log(englishRegions.of("FR")); // "France"
console.log(japaneseRegions.of("FR")); // "フランス"
console.log(spanishRegions.of("FR")); // "Francia"

이 패턴은 국가 선택기, 위치 표시 및 국가 코드를 읽을 수 있는 이름으로 변환하는 모든 인터페이스 요소를 구축하는 데 적합합니다.

언어 코드를 언어 이름으로 변환

언어 코드는 지역 코드와 동일한 패턴을 사용합니다. 언어 코드를 언어 이름으로 변환하려면 type: "language"를 설정합니다:

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en")); // "English"
console.log(languageNames.of("es")); // "Spanish"
console.log(languageNames.of("zh")); // "Chinese"
console.log(languageNames.of("ar")); // "Arabic"

언어 코드는 지역 변형을 위한 지역 하위 태그를 포함할 수 있습니다:

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en-US")); // "American English"
console.log(languageNames.of("en-GB")); // "British English"
console.log(languageNames.of("fr-CA")); // "Canadian French"
console.log(languageNames.of("pt-BR")); // "Brazilian Portuguese"

언어 코드를 언어 전환기, 번역 인터페이스, 언어 기본 설정 선택기에 적합한 이름으로 변환합니다.

각 언어를 자체 언어로 표시하기

언어 전환기는 종종 각 언어를 자체 문자 체계로 표시합니다. 각 대상 언어에 대해 별도의 DisplayNames 인스턴스를 생성합니다:

const english = new Intl.DisplayNames(["en"], { type: "language" });
const french = new Intl.DisplayNames(["fr"], { type: "language" });
const japanese = new Intl.DisplayNames(["ja"], { type: "language" });
const arabic = new Intl.DisplayNames(["ar"], { type: "language" });

console.log(english.of("en")); // "English"
console.log(french.of("fr")); // "français"
console.log(japanese.of("ja")); // "日本語"
console.log(arabic.of("ar")); // "العربية"

사용자는 자신의 언어가 고유 문자로 표시될 때 더 빠르게 인식합니다.

통화 코드를 통화 이름으로 변환하기

통화 코드는 ISO 4217 표준을 따릅니다. 세 글자 통화 코드를 통화 이름으로 변환하려면 type: "currency"를 설정합니다:

const currencyNames = new Intl.DisplayNames(["en"], { type: "currency" });

console.log(currencyNames.of("USD")); // "US Dollar"
console.log(currencyNames.of("EUR")); // "Euro"
console.log(currencyNames.of("GBP")); // "British Pound"
console.log(currencyNames.of("JPY")); // "Japanese Yen"

통화 이름은 표시 로케일에 따라 현지화됩니다:

const englishCurrency = new Intl.DisplayNames(["en"], { type: "currency" });
const germanCurrency = new Intl.DisplayNames(["de"], { type: "currency" });
const japaneseCurrency = new Intl.DisplayNames(["ja"], { type: "currency" });

console.log(englishCurrency.of("EUR")); // "Euro"
console.log(germanCurrency.of("EUR")); // "Euro"
console.log(japaneseCurrency.of("EUR")); // "ユーロ"

이 패턴은 결제 플로우의 통화 선택기, 금융 대시보드, 통화 변환 인터페이스에 적용됩니다.

문자 코드를 문자 이름으로 변환하기

문자 코드는 ISO 15924 표준을 사용합니다. 네 글자 문자 코드를 문자 이름으로 변환하려면 type: "script"를 설정합니다:

const scriptNames = new Intl.DisplayNames(["en"], { type: "script" });

console.log(scriptNames.of("Latn")); // "Latin"
console.log(scriptNames.of("Arab")); // "Arabic"
console.log(scriptNames.of("Cyrl")); // "Cyrillic"
console.log(scriptNames.of("Hans")); // "Simplified Chinese"
console.log(scriptNames.of("Hant")); // "Traditional Chinese"

문자 이름은 사용자 인터페이스에서 덜 자주 나타나지만, 다국어 콘텐츠 관리 시스템과 문자 체계를 구분하는 언어 선택 인터페이스에서 중요해집니다.

달력 코드를 달력 이름으로 변환하기

달력 체계는 문화권마다 다릅니다. type: "calendar"를 설정하여 달력 식별자를 달력 이름으로 변환하세요:

const calendarNames = new Intl.DisplayNames(["en"], { type: "calendar" });

console.log(calendarNames.of("gregory")); // "Gregorian Calendar"
console.log(calendarNames.of("japanese")); // "Japanese Calendar"
console.log(calendarNames.of("buddhist")); // "Buddhist Calendar"
console.log(calendarNames.of("hebrew")); // "Hebrew Calendar"
console.log(calendarNames.of("islamic")); // "Islamic Calendar"
console.log(calendarNames.of("chinese")); // "Chinese Calendar"

이는 일정 관리 애플리케이션, 달력 시스템 선택 기능이 있는 날짜 선택기, 국제화된 달력 인터페이스에 유용합니다.

날짜 및 시간 필드 코드를 필드 이름으로 변환하기

날짜 및 시간 인터페이스에는 연도, 월, 일과 같은 레이블이 지정된 필드가 포함됩니다. type: "dateTimeField"를 설정하여 필드 식별자를 현지화된 필드 이름으로 변환하세요:

const dateFields = new Intl.DisplayNames(["en"], { type: "dateTimeField" });

console.log(dateFields.of("year")); // "year"
console.log(dateFields.of("month")); // "month"
console.log(dateFields.of("day")); // "day"
console.log(dateFields.of("hour")); // "hour"
console.log(dateFields.of("minute")); // "minute"
console.log(dateFields.of("weekday")); // "day of the week"
console.log(dateFields.of("dayPeriod")); // "AM/PM"
console.log(dateFields.of("timeZoneName")); // "time zone"

이러한 필드 이름은 표시 언어에 맞게 현지화됩니다:

const englishFields = new Intl.DisplayNames(["en"], { type: "dateTimeField" });
const spanishFields = new Intl.DisplayNames(["es"], { type: "dateTimeField" });
const japaneseFields = new Intl.DisplayNames(["ja"], { type: "dateTimeField" });

console.log(englishFields.of("month")); // "month"
console.log(spanishFields.of("month")); // "mes"
console.log(japaneseFields.of("month")); // "月"

유효한 필드 식별자에는 era, year, quarter, month, weekOfYear, weekday, day, dayPeriod, hour, minute, second 및 timeZoneName가 포함됩니다.

이 패턴은 적절하게 현지화된 레이블을 사용하여 접근 가능한 날짜 선택기, 캘린더 인터페이스 및 시간 선택 컴포넌트를 구축하는 것을 지원합니다.

스타일 옵션으로 표시 길이 제어하기

style 옵션은 출력이 얼마나 상세하게 표시되는지를 제어합니다. 세 가지 값은 서로 다른 길이를 생성합니다:

const longNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "long",
});

const shortNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "short",
});

const narrowNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "narrow",
});

console.log(longNames.of("US")); // "United States"
console.log(shortNames.of("US")); // "US"
console.log(narrowNames.of("US")); // "US"

long 스타일(기본값)은 전체 이름을 생성합니다. short 및 narrow 스타일은 사용 가능한 경우 축약된 형식을 생성하지만, 모든 코드에 짧은 변형이 있는 것은 아닙니다.

스타일은 언어 이름에서 더욱 중요해집니다:

const longLanguages = new Intl.DisplayNames(["en"], {
  type: "language",
  style: "long",
});

const shortLanguages = new Intl.DisplayNames(["en"], {
  type: "language",
  style: "short",
});

console.log(longLanguages.of("en-US")); // "American English"
console.log(shortLanguages.of("en-US")); // "US English"

양식 및 상세 인터페이스에서 전체 레이블을 표시하려면 long를 사용하세요. 모바일 내비게이션이나 공간이 제한된 UI 요소와 같은 컴팩트한 디스플레이에는 short 또는 narrow를 사용하세요.

languageDisplay로 지역 언어 변형 처리하기

지역 하위 태그가 있는 언어 코드는 방언으로 표시되거나 지역 한정자가 있는 표준 언어 이름으로 표시될 수 있습니다. languageDisplay 옵션은 이 동작을 제어하며 type: "language"인 경우에만 적용됩니다:

const dialectNames = new Intl.DisplayNames(["en"], {
  type: "language",
  languageDisplay: "dialect",
});

const standardNames = new Intl.DisplayNames(["en"], {
  type: "language",
  languageDisplay: "standard",
});

console.log(dialectNames.of("nl-BE")); // "Flemish"
console.log(standardNames.of("nl-BE")); // "Dutch (Belgium)"

console.log(dialectNames.of("en-AU")); // "Australian English"
console.log(standardNames.of("en-AU")); // "English (Australia)"

dialect 값(기본값)은 일반적인 이름을 사용하여 지역 변형을 표시합니다. standard 값은 항상 괄호 안에 지역 한정자가 있는 기본 언어를 표시합니다.

지역 변형에 사용자가 인식하는 잘 알려진 이름이 있는 경우 dialect를 선택하세요. 일관된 형식이 필요하거나 덜 일반적인 언어-지역 조합을 사용하는 경우 standard를 선택하세요.

유효하지 않은 코드에 대한 폴백 동작 제어하기

of() 메서드는 해당하는 표시 이름이 없을 수 있는 코드를 받습니다. fallback 옵션은 이러한 경우 어떻게 처리할지 결정합니다:

const withCodeFallback = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "code",
});

const withNoneFallback = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "none",
});

console.log(withCodeFallback.of("ZZ")); // "ZZ"
console.log(withNoneFallback.of("ZZ")); // undefined

code 값(기본값)은 표시 이름이 없을 때 입력 코드를 반환합니다. none 값은 매핑되지 않은 코드에 대해 undefined를 반환합니다.

코드 자체로 폴백되더라도 항상 표시할 문자열 값이 필요한 경우 code를 사용하세요. 유효하지 않은 코드를 감지하고 명시적으로 처리해야 하는 경우 none를 사용하세요:

const regionNames = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "none",
});

function getRegionName(code) {
  const name = regionNames.of(code);
  if (name === undefined) {
    return "Unknown region";
  }
  return name;
}

console.log(getRegionName("US")); // "United States"
console.log(getRegionName("INVALID")); // "Unknown region"

국가 선택기 컴포넌트 구축

Intl.DisplayNames API는 인터페이스 컴포넌트에 직접 통합됩니다. 이 예제는 사용자의 언어로 국가 이름을 표시하는 국가 선택기를 구축합니다:

function CountrySelector({ locale, value, onChange }) {
  const regionNames = new Intl.DisplayNames([locale], { type: "region" });

  const countries = [
    "US",
    "GB",
    "CA",
    "AU",
    "FR",
    "DE",
    "JP",
    "CN",
    "BR",
    "IN",
  ];

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Select a country</option>
      {countries.map((code) => (
        <option key={code} value={code}>
          {regionNames.of(code)}
        </option>
      ))}
    </select>
  );
}

컴포넌트는 표시 언어를 제어하는 locale prop을 받습니다. locale prop을 변경하면 번역된 국가 이름으로 드롭다운이 다시 렌더링됩니다.

언어 전환기 컴포넌트 구축

언어 전환기는 각 언어를 자체 문자 체계로 표시합니다. 각 언어에 대해 DisplayNames 인스턴스를 생성하세요:

function LanguageSwitcher({ currentLocale, onLocaleChange }) {
  const languages = [
    { code: "en", name: "English" },
    { code: "es", name: "Español" },
    { code: "fr", name: "Français" },
    { code: "de", name: "Deutsch" },
    { code: "ja", name: "日本語" },
    { code: "zh", name: "中文" },
  ];

  return (
    <div>
      {languages.map((lang) => {
        const displayNames = new Intl.DisplayNames([lang.code], {
          type: "language",
        });
        const nativeName = displayNames.of(lang.code);

        return (
          <button
            key={lang.code}
            onClick={() => onLocaleChange(lang.code)}
            className={currentLocale === lang.code ? "active" : ""}
          >
            {nativeName}
          </button>
        );
      })}
    </div>
  );
}

각 버튼은 언어 이름을 자체 문자로 표시합니다. 사용자는 현재 인터페이스 언어와 관계없이 자신의 언어를 즉시 인식할 수 있습니다.

통화 선택기 컴포넌트 구축

통화 선택기는 현지화된 통화 이름의 이점을 활용합니다. 이 예제는 표시 언어에 맞춰 조정되는 통화 선택기를 생성합니다:

function CurrencySelector({ locale, value, onChange }) {
  const currencyNames = new Intl.DisplayNames([locale], { type: "currency" });

  const currencies = ["USD", "EUR", "GBP", "JPY", "CNY", "CAD", "AUD"];

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Select currency</option>
      {currencies.map((code) => (
        <option key={code} value={code}>
          {code} - {currencyNames.of(code)}
        </option>
      ))}
    </select>
  );
}

드롭다운은 통화 코드와 현지화된 통화 이름을 모두 표시합니다. 다른 지역의 사용자는 자신의 언어로 통화 이름을 볼 수 있습니다.

지원되는 모든 값 가져오기

Intl.supportedValuesOf() 메서드는 각 타입에 대해 지원되는 모든 값의 배열을 반환합니다. 이를 통해 하드코딩된 코드 목록을 제거할 수 있습니다:

const regions = Intl.supportedValuesOf("region");
console.log(regions); // ["AD", "AE", "AF", "AG", "AI", ...]

const languages = Intl.supportedValuesOf("language");
console.log(languages); // ["aa", "ab", "ae", "af", "ak", ...]

const currencies = Intl.supportedValuesOf("currency");
console.log(currencies); // ["AED", "AFN", "ALL", "AMD", ...]

const calendars = Intl.supportedValuesOf("calendar");
console.log(calendars); // ["buddhist", "chinese", "coptic", ...]

지원되는 모든 값을 자동으로 포함하는 동적 선택기를 구축합니다:

function UniversalCountrySelector({ locale, value, onChange }) {
  const regionNames = new Intl.DisplayNames([locale], { type: "region" });
  const allRegions = Intl.supportedValuesOf("region");

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Select a country</option>
      {allRegions.map((code) => (
        <option key={code} value={code}>
          {regionNames.of(code)}
        </option>
      ))}
    </select>
  );
}

이 컴포넌트는 하드코딩된 목록을 유지하지 않고도 브라우저에서 지원하는 모든 지역 코드를 포함합니다.

코드 형식 요구사항 이해

각 유형은 특정 형식의 코드를 요구합니다. 잘못된 형식은 표시 이름 대신 대체 동작을 생성합니다.

지역 코드는 ISO 3166-1 alpha-2(두 글자) 또는 UN M.49(세 자리 숫자)를 따릅니다:

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States" (ISO 3166-1)
console.log(regionNames.of("001")); // "world" (UN M.49)
console.log(regionNames.of("150")); // "Europe" (UN M.49)

언어 코드는 BCP 47을 따르며, ISO 639 언어 코드와 선택적 지역 및 문자 하위 태그를 결합합니다:

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en")); // "English"
console.log(languageNames.of("en-US")); // "American English"
console.log(languageNames.of("zh-Hans")); // "Simplified Chinese"
console.log(languageNames.of("zh-Hans-CN")); // "Simplified Chinese (China)"

통화 코드는 ISO 4217을 따릅니다(세 글자):

const currencyNames = new Intl.DisplayNames(["en"], { type: "currency" });

console.log(currencyNames.of("USD")); // "US Dollar"
console.log(currencyNames.of("EUR")); // "Euro"

문자 코드는 ISO 15924를 따릅니다(네 글자, 대문자):

const scriptNames = new Intl.DisplayNames(["en"], { type: "script" });

console.log(scriptNames.of("Latn")); // "Latin"
console.log(scriptNames.of("Arab")); // "Arabic"

코드 비교는 대소문자를 구분하지 않지만, 표준 대문자 표기를 따르면 가독성이 향상됩니다:

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States"
console.log(regionNames.of("us")); // "United States"
console.log(regionNames.of("Us")); // "United States"

브라우저 지원 및 호환성

Intl.DisplayNames API는 2021년부터 모든 주요 브라우저에서 사용할 수 있게 되었습니다. 최신 애플리케이션은 폴리필 없이 이를 사용할 수 있습니다.

language, region, script, currency 타입을 포함한 기본 API는 범용적으로 지원됩니다. calendar 및 dateTimeField 타입은 이후 브라우저 버전에서 등장했지만 2025년 기준으로 광범위하게 지원됩니다.

필요한 경우 런타임에 기능 지원을 확인하세요:

if (typeof Intl.DisplayNames !== "undefined") {
  const regionNames = new Intl.DisplayNames(["en"], { type: "region" });
  console.log(regionNames.of("US"));
} else {
  console.log("Intl.DisplayNames not supported");
}

구형 브라우저를 지원하는 애플리케이션의 경우, API를 사용할 수 없을 때 정적 조회 테이블이나 서드파티 라이브러리로 대체하세요.

캐싱을 통한 성능 최적화

DisplayNames 인스턴스 생성은 오버헤드가 최소화되어 있지만, 많은 코드를 변환하는 애플리케이션은 인스턴스를 재사용해야 합니다:

const cache = new Map();

function getDisplayNames(locale, type) {
  const key = `${locale}-${type}`;

  if (!cache.has(key)) {
    cache.set(key, new Intl.DisplayNames([locale], { type }));
  }

  return cache.get(key);
}

function getCountryName(locale, code) {
  const displayNames = getDisplayNames(locale, "region");
  return displayNames.of(code);
}

console.log(getCountryName("en", "US")); // "United States"
console.log(getCountryName("en", "FR")); // "France"
console.log(getCountryName("es", "US")); // "Estados Unidos"

캐시는 로케일과 타입을 키로 하여 인스턴스를 저장합니다. 후속 호출은 새 인스턴스를 생성하는 대신 기존 인스턴스를 재사용합니다.

이 패턴은 지역화된 데이터의 대규모 테이블 렌더링과 같이 수백 또는 수천 개의 코드를 변환하는 핫 코드 경로에서 가장 중요합니다.

대안적 접근 방식과의 비교

Intl.DisplayNames API 이전에는 애플리케이션이 코드를 이름으로 변환하기 위해 여러 접근 방식을 사용했습니다.

하드코딩된 조회 테이블은 유지 관리가 필요했으며 미리 결정된 언어만 지원했습니다:

const countryNames = {
  US: "United States",
  GB: "United Kingdom",
  FR: "France",
};

function getCountryName(code) {
  return countryNames[code] || code;
}

이 접근 방식은 각 언어마다 별도의 조회 테이블이 필요하기 때문에 새로운 언어를 추가할 때 문제가 발생합니다.

서드파티 라이브러리는 지역화 데이터를 제공했지만 번들 크기가 증가했습니다:

import countries from "i18n-iso-countries";
import countriesEN from "i18n-iso-countries/langs/en.json";
import countriesES from "i18n-iso-countries/langs/es.json";

countries.registerLocale(countriesEN);
countries.registerLocale(countriesES);

console.log(countries.getName("US", "en")); // "United States"
console.log(countries.getName("US", "es")); // "Estados Unidos"

라이브러리는 번들에 수 킬로바이트의 데이터를 추가하며, 새로운 국가가 등장하거나 이름이 변경될 때 업데이트가 필요합니다.

Intl.DisplayNames API는 두 가지 문제를 모두 해결합니다. 브라우저가 데이터를 유지 관리하여 최신 상태를 유지하고 번들 크기 문제를 제거합니다. 이 데이터는 추가 다운로드 없이 브라우저가 지원하는 모든 언어를 지원합니다.