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)

언어 코드는 ISO 639 언어 코드와 선택적 지역 및 스크립트 서브태그를 결합한 BCP 47을 따릅니다:

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는 두 가지 문제를 모두 해결합니다. 브라우저가 데이터를 유지하여 최신 상태를 유지하고 번들 크기 문제를 제거합니다. 이 데이터는 추가 다운로드 없이 브라우저가 지원하는 모든 언어를 지원합니다.