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 (Sunday)
console.log(weekInfo.weekend); // [6, 7] (Saturday, Sunday)
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 애플리케이션에서 로케일 식별자를 다루는 표준 방법을 제공합니다.