Intl.Locale API - JavaScript i18n

소개

여러 언어와 지역을 위한 애플리케이션을 구축할 때, en-US, fr-FR 또는 zh-Hans-CN과 같은 로케일 식별자를 접하게 됩니다. 이러한 문자열은 브라우저 API, HTTP 헤더 및 사용자 환경설정에 나타납니다. 이들은 언어, 지역, 문자 체계 및 서식 지정 환경설정에 관한 정보를 인코딩합니다.

Intl.Locale API는 이러한 불투명한 문자열을 검사하고 조작할 수 있는 구조화된 객체로 변환합니다. 문자열을 수동으로 파싱하거나 zh-Hans-CN이 무엇을 의미하는지 추측하는 대신, 로케일 객체를 생성하고 해당 속성을 직접 읽을 수 있습니다.

이 가이드는 로케일 식별자가 어떻게 작동하는지, Intl.Locale API를 사용하여 이를 다루는 방법, 그리고 구조화된 로케일 객체가 실제 문제 해결에 도움이 되는 경우를 설명합니다.

로케일 식별자 이해하기

로케일 식별자는 날짜, 숫자, 통화 및 텍스트 서식 지정을 위한 문화적 환경설정을 지정하는 문자열입니다. 식별자는 하이픈으로 구분된 여러 구성 요소를 포함합니다.

가장 일반적인 구조는 BCP 47 표준을 따릅니다:

language-script-region-variant-extensions

언어 코드를 제외한 각 구성 요소는 선택 사항입니다.

언어 코드

언어 코드는 ISO 639에서 두 글자 또는 세 글자를 사용합니다. 일반적인 예시:

en 영어
es 스페인어
fr 프랑스어
de 독일어
ja 일본어
zh 중국어
ar 아랍어

언어 코드는 항상 소문자이며 식별자의 맨 앞에 나타납니다.

지역 코드

지역 코드는 ISO 3166-1의 두 개의 대문자를 사용하여 지리적 영역을 지정합니다. 이는 사용할 언어의 변형을 나타냅니다:

en-US 미국 영어
en-GB 영국 영어
es-ES 유럽 스페인어
es-MX 멕시코 스페인어
fr-FR 프랑스에서 사용되는 프랑스어
fr-CA 캐나다 프랑스어

지역 코드는 서식 지정 규칙을 변경합니다. 미국 영어는 MM/DD/YYYY 날짜 형식을 사용하는 반면, 영국 영어는 DD/MM/YYYY 형식을 사용합니다.

스크립트 코드

스크립트 코드는 첫 글자가 대문자인 네 글자로 표기 체계를 지정합니다. 이는 여러 스크립트로 작성되는 언어에 중요합니다:

zh-Hans 간체 중국어 문자용
zh-Hant 번체 중국어 문자용
sr-Cyrl 키릴 문자로 된 세르비아어용
sr-Latn 라틴 문자로 된 세르비아어용

대부분의 로케일은 언어가 기본 스크립트를 암시하기 때문에 스크립트 코드를 생략합니다. 영어는 기본적으로 라틴 스크립트를 사용하므로 en-Latn 대신 en으로 표기합니다.

확장 태그

확장 태그는 로케일 식별자에 서식 지정 기본 설정을 추가합니다. 이는 -u-로 시작하고 그 뒤에 키-값 쌍이 옵니다:

en-US-u-ca-gregory-nu-latn-hc-h12

일반적인 확장 키:

ca 달력 시스템용 (gregory, buddhist, islamic)
nu 숫자 체계용 (latn, arab, hanidec)
hc 시간 주기용 (h12, h23, h11, h24)

확장은 언어나 지역을 변경하지 않고 포맷터가 데이터를 표시하는 방식을 사용자 정의합니다.

로케일 객체 생성하기

'Intl.Locale' 생성자는 로케일 식별자 문자열을 받아 구조화된 객체를 반환합니다:

const locale = new Intl.Locale("en-US");

console.log(locale.language); // "en"
console.log(locale.region); // "US"

속성을 재정의하거나 추가하기 위해 옵션 객체를 전달할 수도 있습니다:

const locale = new Intl.Locale("en", {
  region: "GB",
  hourCycle: "h23"
});

console.log(locale.baseName); // "en-GB"
console.log(locale.hourCycle); // "h23"

식별자가 유효하지 않으면 생성자는 RangeError를 발생시킵니다:

try {
  const invalid = new Intl.Locale("invalid-locale-code");
} catch (error) {
  console.error(error.message); // "invalid language subtag: invalid"
}

이 유효성 검사는 잘못된 형식의 로케일 식별자를 포맷터에 전달하기 전에 발견할 수 있도록 합니다.

로케일 속성 읽기

로케일 객체는 식별자 문자열의 구성 요소에 해당하는 속성을 노출합니다. 모든 속성은 읽기 전용입니다.

핵심 속성

'language' 속성은 언어 코드를 반환합니다:

const locale = new Intl.Locale("fr-CA");
console.log(locale.language); // "fr"

'region' 속성은 지역 코드를 반환합니다:

const locale = new Intl.Locale("fr-CA");
console.log(locale.region); // "CA"

'script' 속성은 존재하는 경우 스크립트 코드를 반환합니다:

const locale = new Intl.Locale("zh-Hans-CN");
console.log(locale.script); // "Hans"

'baseName' 속성은 확장자 없이 완전한 핵심 식별자를 반환합니다:

const locale = new Intl.Locale("en-US-u-ca-gregory-nu-latn");
console.log(locale.baseName); // "en-US"

언어와 지역은 필요하지만 서식 지정 기본 설정을 무시하려면 'baseName'을 사용하세요.

확장 속성

확장 속성은 '-u-' 확장 태그의 값을 반환하거나 지정되지 않은 경우 'undefined'를 반환합니다.

'calendar' 속성은 달력 시스템을 반환합니다:

const locale = new Intl.Locale("ar-SA-u-ca-islamic");
console.log(locale.calendar); // "islamic"

'numberingSystem' 속성은 숫자 체계를 반환합니다:

const locale = new Intl.Locale("ar-EG-u-nu-arab");
console.log(locale.numberingSystem); // "arab"

'hourCycle' 속성은 시간 주기 기본 설정을 반환합니다:

const locale = new Intl.Locale("en-US-u-hc-h23");
console.log(locale.hourCycle); // "h23"

'caseFirst' 속성은 콜레이션 대소문자 기본 설정을 반환합니다:

const locale = new Intl.Locale("en-US-u-kf-upper");
console.log(locale.caseFirst); // "upper"

'numeric' 속성은 숫자 콜레이션이 활성화되었는지 여부를 나타냅니다:

const locale = new Intl.Locale("en-US-u-kn-true");
console.log(locale.numeric); // true

이러한 속성을 사용하면 확장 문자열을 수동으로 구문 분석하지 않고도 서식 지정 기본 설정을 검사할 수 있습니다.

로케일 정보 조회

'Intl.Locale' API는 로케일에 사용 가능한 옵션의 배열을 반환하는 메서드를 제공합니다. 이러한 메서드는 사용자 인터페이스를 구축하고 서식 지정 선택을 검증하는 데 도움이 됩니다.

사용 가능한 달력

'getCalendars()' 메서드는 로케일에서 일반적으로 사용되는 달력 시스템을 반환합니다:

const locale = new Intl.Locale("th-TH");
const calendars = locale.getCalendars();
console.log(calendars); // ["buddhist", "gregory"]

첫 번째 요소는 기본 달력입니다. 태국 로케일은 기본적으로 불교 달력을 사용하지만 그레고리안 달력도 사용합니다.

사용 가능한 콜레이션

문자열 정렬을 위한 콜레이션 유형을 반환하는 getCollations() 메서드:

const locale = new Intl.Locale("de-DE");
const collations = locale.getCollations();
console.log(collations); // ["phonebk", "emoji", "eor"]

독일어는 표준 유니코드 콜레이션과 다르게 문자열을 정렬하는 전화번호부 콜레이션을 가지고 있습니다.

사용 가능한 시간 표기 방식

시간 표기 형식을 반환하는 getHourCycles() 메서드:

const locale = new Intl.Locale("en-US");
const hourCycles = locale.getHourCycles();
console.log(hourCycles); // ["h12"]

미국 영어는 기본적으로 12시간제를 사용합니다. 다른 많은 로케일은 24시간제를 위해 ["h23"]을 반환합니다.

사용 가능한 숫자 체계

로케일에서 일반적으로 사용되는 숫자 체계를 반환하는 getNumberingSystems() 메서드:

const locale = new Intl.Locale("ar-EG");
const numberingSystems = locale.getNumberingSystems();
console.log(numberingSystems); // ["arab", "latn"]

아랍어 로케일은 일반적으로 아랍-인도 숫자와 라틴 숫자를 모두 지원합니다.

텍스트 방향

텍스트 순서 정보를 반환하는 getTextInfo() 메서드:

const locale = new Intl.Locale("ar-SA");
const textInfo = locale.getTextInfo();
console.log(textInfo.direction); // "rtl"

아랍어와 히브리어 같은 오른쪽에서 왼쪽으로 읽는 언어는 "rtl"을 반환합니다. 왼쪽에서 오른쪽으로 읽는 언어는 "ltr"을 반환합니다.

주간 규칙

로케일의 주간 구조를 반환하는 getWeekInfo() 메서드:

const locale = new Intl.Locale("en-US");
const weekInfo = locale.getWeekInfo();
console.log(weekInfo.firstDay); // 7 (일요일)
console.log(weekInfo.weekend); // [6, 7] (토요일, 일요일)
console.log(weekInfo.minimalDays); // 1

주간 규칙은 지역에 따라 다릅니다. 미국의 주는 일요일에 시작하지만, 대부분의 유럽 국가는 월요일에 시작합니다.

시간대

로케일 지역의 시간대를 반환하는 getTimeZones() 메서드:

const locale = new Intl.Locale("en-US");
const timeZones = locale.getTimeZones();
console.log(timeZones); // ["America/New_York", "America/Chicago", ...]

이 메서드는 해당 지역 코드에 대한 IANA 시간대 식별자를 반환합니다.

로케일 식별자 최대화하기

maximize() 메서드는 완전한 식별자를 만들기 위해 가능성이 높은 하위 태그를 추가합니다. 이는 언어 데이터를 기반으로 누락된 스크립트 및 지역 코드를 추론합니다.

언어 코드만 지정하면 maximize()는 가장 일반적인 스크립트와 지역을 추가합니다:

const locale = new Intl.Locale("en");
const maximized = locale.maximize();
console.log(maximized.baseName); // "en-Latn-US"

영어는 라틴 스크립트와 미국 지역이 가장 일반적인 연관성이기 때문에 기본값으로 설정됩니다.

중국어 최대화는 스크립트에 따라 달라집니다:

const simplified = new Intl.Locale("zh-Hans");
const maximized = simplified.maximize();
console.log(maximized.baseName); // "zh-Hans-CN"

const traditional = new Intl.Locale("zh-Hant");
const maximizedTrad = traditional.maximize();
console.log(maximizedTrad.baseName); // "zh-Hant-TW"

간체 중국어는 중국과 연관되고, 번체 중국어는 대만과 연관됩니다.

사용자 입력을 정규화하거나 로케일 식별자를 비교할 때 maximize()를 사용하세요. 이는 암시적 정보를 명시적으로 만듭니다.

로케일 식별자 최소화하기

minimize() 메서드는 중복되는 하위 태그를 제거하여 가장 짧은 동등한 식별자를 만듭니다. 이는 기본값과 일치하는 스크립트 및 지역 코드를 제거합니다.

로케일이 기본 스크립트와 지역을 사용할 때, minimize()는 이를 제거합니다:

const locale = new Intl.Locale("en-Latn-US");
const minimized = locale.minimize();
console.log(minimized.baseName); // "en"

라틴 스크립트와 미국 지역은 영어의 기본값이므로 정보 손실 없이 제거할 수 있습니다.

기본값이 아닌 지역을 가진 로케일의 경우, minimize()는 지역을 유지합니다:

const locale = new Intl.Locale("en-Latn-GB");
const minimized = locale.minimize();
console.log(minimized.baseName); // "en-GB"

영국 영어는 기본값과 다르기 때문에 지역 코드가 필요합니다.

의미를 보존하면서 저장소나 URL에 사용할 간결한 식별자를 만들 때 minimize()를 사용하세요.

문자열로 변환하기

toString() 메서드는 확장을 포함한 전체 로케일 식별자를 반환합니다:

const locale = new Intl.Locale("en-US", {
  calendar: "gregory",
  numberingSystem: "latn",
  hourCycle: "h12"
});

console.log(locale.toString()); // "en-US-u-ca-gregory-hc-h12-nu-latn"

문자열 표현은 다른 Intl API에 전달하거나 구성 데이터로 저장하는 데 유효합니다.

로케일 객체를 암시적으로 문자열로 변환할 수도 있습니다:

const locale = new Intl.Locale("fr-FR");
const formatter = new Intl.DateTimeFormat(locale);

DateTimeFormat 생성자는 로케일 객체를 직접 받아들이고 내부적으로 toString()을 호출합니다.

실용적인 사용 사례

Intl.Locale API는 국제화된 애플리케이션을 구축할 때 발생하는 여러 일반적인 문제를 해결합니다.

로케일 선택기 구축하기

로케일 선택기는 사용자가 언어와 지역을 선택할 수 있게 해줍니다. Intl.Locale API는 사용자 선택을 파싱하고 검증하는 데 도움이 됩니다:

function createLocaleSelector(locales) {
  const options = locales.map(identifier => {
    const locale = new Intl.Locale(identifier);
    const displayName = new Intl.DisplayNames([identifier], { type: "language" });

    return {
      value: locale.toString(),
      label: displayName.of(locale.language),
      region: locale.region
    };
  });

  return options;
}

const options = createLocaleSelector(["en-US", "en-GB", "fr-FR", "es-MX"]);
console.log(options);
// [
//   { value: "en-US", label: "English", region: "US" },
//   { value: "en-GB", label: "English", region: "GB" },
//   { value: "fr-FR", label: "French", region: "FR" },
//   { value: "es-MX", label: "Spanish", region: "MX" }
// ]

로케일 입력 검증하기

사용자 입력이나 구성 파일에서 로케일 식별자를 받을 때, 사용하기 전에 검증하세요:

function validateLocale(identifier) {
  try {
    const locale = new Intl.Locale(identifier);
    return {
      valid: true,
      locale: locale.toString(),
      language: locale.language,
      region: locale.region
    };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

console.log(validateLocale("en-US")); // { valid: true, locale: "en-US", ... }
console.log(validateLocale("invalid")); // { valid: false, error: "..." }

폴백을 위한 언어 추출하기

언어 폴백 체인을 구현할 때, 지역 없이 언어 코드만 추출하세요:

function getLanguageFallback(identifier) {
  const locale = new Intl.Locale(identifier);
  const fallbacks = [locale.toString()];

  if (locale.region) {
    const languageOnly = new Intl.Locale(locale.language);
    fallbacks.push(languageOnly.toString());
  }

  fallbacks.push("en");

  return fallbacks;
}

console.log(getLanguageFallback("fr-CA"));
// ["fr-CA", "fr", "en"]

이렇게 하면 특정 로케일, 지역 없는 언어, 그리고 기본 언어 순으로 시도하는 폴백 체인이 생성됩니다.

포맷터 구성하기

로케일 객체를 사용하여 특정 환경설정으로 Intl 포맷터를 구성하세요:

function createFormatter(baseLocale, options = {}) {
  const locale = new Intl.Locale(baseLocale, {
    calendar: options.calendar || "gregory",
    numberingSystem: options.numberingSystem || "latn",
    hourCycle: options.hourCycle || "h23"
  });

  return {
    date: new Intl.DateTimeFormat(locale),
    number: new Intl.NumberFormat(locale),
    locale: locale.toString()
  };
}

const formatter = createFormatter("ar-SA", {
  calendar: "islamic",
  numberingSystem: "arab"
});

console.log(formatter.locale); // "ar-SA-u-ca-islamic-nu-arab"

사용자 환경설정 감지하기

브라우저 API는 사용자 환경설정을 이해하기 위해 파싱할 수 있는 로케일 문자열을 제공합니다:

function getUserPreferences() {
  const userLocale = new Intl.Locale(navigator.language);
  const hourCycles = userLocale.getHourCycles();
  const calendars = userLocale.getCalendars();
  const textInfo = userLocale.getTextInfo();

  return {
    language: userLocale.language,
    region: userLocale.region,
    preferredHourCycle: hourCycles[0],
    preferredCalendar: calendars[0],
    textDirection: textInfo.direction
  };
}

const preferences = getUserPreferences();
console.log(preferences);
// { language: "en", region: "US", preferredHourCycle: "h12", ... }

이는 사용자의 브라우저 설정을 기반으로 사용자 환경설정 프로필을 생성합니다.

브라우저 지원

Intl.Locale API는 모든 최신 브라우저에서 작동합니다. Chrome, Firefox, Safari 및 Edge는 이 가이드에서 설명한 생성자, 속성 및 메서드에 대한 전체 지원을 제공합니다.

getCalendars(), getCollations(), getHourCycles(), getNumberingSystems(), getTextInfo(), getTimeZones(), getWeekInfo()와 같은 최신 메서드는 최신 브라우저 버전이 필요합니다. 구형 브라우저를 지원하는 경우 이러한 메서드를 사용하기 전에 브라우저 호환성 표를 확인하세요.

Node.js는 버전 12부터 Intl.Locale API를 지원하며, 버전 18 이상에서는 모든 메서드를 완전히 지원합니다.

요약

Intl.Locale API는 로케일 식별자 문자열을 검사하고 조작할 수 있는 구조화된 객체로 변환합니다. 문자열을 수동으로 파싱하는 대신, 로케일 객체를 생성하고 해당 속성을 읽을 수 있습니다.

핵심 개념:

로케일 식별자는 언어, 스크립트, 지역 및 확장 구성 요소를 포함합니다
Intl.Locale 생성자는 식별자를 검증하고 객체를 생성합니다
language, region, calendar와 같은 속성은 구조화된 접근을 제공합니다
getCalendars() 및 getHourCycles()와 같은 메서드는 사용 가능한 옵션을 반환합니다
maximize() 및 minimize() 메서드는 식별자를 정규화합니다
로케일 객체는 다른 Intl API와 직접 작동합니다

로케일 선택기를 구축하거나, 사용자 입력을 검증하거나, 폴백 체인을 구현하거나, 포맷터를 구성할 때 Intl.Locale API를 사용하세요. 이는 JavaScript 애플리케이션에서 로케일 식별자를 다루는 표준 방법을 제공합니다.