🌍 국제화(i18n)와 JavaScript Intl API 완벽 가이드

[language]-[script]-[region]-[extension]
  ko         Kore      KR       -u-nu-hanidec

// 사용자가 요청한 언어 중 시스템이 지원하는 언어를 매칭하는 로케일 협상
const requestedLocales = ['fr-CA', 'fr', 'en-US'];
const supported = Intl.DateTimeFormat.supportedLocalesOf(requestedLocales, {
  localeMatcher: 'lookup' // 'lookup' 또는 'best fit'
});
console.log(supported); // ['fr-CA', 'fr', 'en-US']

const formatter = new Intl.NumberFormat(navigator.languages);

const now = new Date('2026-10-09T14:30:00Z');

// 1. 한국 로케일: 긴 형식
const koFormatter = new Intl.DateTimeFormat('ko-KR', {
  dateStyle: 'full',
  timeStyle: 'medium',
  timeZone: 'Asia/Seoul'
});
console.log(koFormatter.format(now));
// "2026년 10월 9일 금요일 오후 11:30:00"

// 2. 미국 로케일: 짧은 형식
const usFormatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'short',
  timeStyle: 'short',
  timeZone: 'America/New_York'
});
console.log(usFormatter.format(now));
// "10/9/26, 10:30 AM"

const startDate = new Date('2026-10-09T09:00:00');
const endDate = new Date('2026-10-12T18:00:00');

const rangeFormatter = new Intl.DateTimeFormat('ko-KR', {
  month: 'short',
  day: 'numeric'
});

console.log(rangeFormatter.formatRange(startDate, endDate));
// "10월 9일 ~ 12일"

const amount = 1234567.89;

// 통화 표기 (원화 vs 미국 달러 vs 유로)
const krwFormat = new Intl.NumberFormat('ko-KR', { style: 'currency', currency: 'KRW' });
const usdFormat = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
const eurFormat = new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' });

console.log(krwFormat.format(amount)); // "₩1,234,568" (원화는 정수 단위 기본 반올림)
console.log(usdFormat.format(amount)); // "$1,234,567.89"
console.log(eurFormat.format(amount)); // "1.234.567,89 €"

// 콤팩트 숫자 표기
const viewsFormatKo = new Intl.NumberFormat('ko-KR', { notation: 'compact' });
const viewsFormatEn = new Intl.NumberFormat('en-US', { notation: 'compact' });

console.log(viewsFormatKo.format(3450000)); // "345만"
console.log(viewsFormatEn.format(3450000)); // "3.5M"

// SI 물리 단위 표기
const speedFormat = new Intl.NumberFormat('ko-KR', {
  style: 'unit',
  unit: 'kilometer-per-hour',
  unitDisplay: 'long'
});
console.log(speedFormat.format(120)); // "시속 120킬로미터"

const rtfKo = new Intl.RelativeTimeFormat('ko-KR', { numeric: 'auto' });
const rtfEn = new Intl.RelativeTimeFormat('en-US', { numeric: 'auto' });

console.log(rtfKo.format(-1, 'day')); // "어제" (`numeric: 'always'`면 "1일 전")
console.log(rtfKo.format(0, 'day'));  // "오늘"
console.log(rtfKo.format(3, 'day'));  // "3일 후"
console.log(rtfKo.format(-15, 'minute')); // "15분 전"

console.log(rtfEn.format(-1, 'day')); // "yesterday"
console.log(rtfEn.format(2, 'month')); // "in 2 months"

// 영어 복수형 규칙 판별
const prEn = new Intl.PluralRules('en-US');
console.log(prEn.select(0)); // "other" (영어는 0개일 때 0 items)
console.log(prEn.select(1)); // "one"
console.log(prEn.select(5)); // "other"

// 아랍어 복수형 규칙 판별
const prAr = new Intl.PluralRules('ar-EG');
console.log(prAr.select(0));  // "zero"
console.log(prAr.select(1));  // "one"
console.log(prAr.select(2));  // "two"
console.log(prAr.select(3));  // "few"
console.log(prAr.select(15)); // "many"
console.log(prAr.select(100));// "other"

function getMessage(count, locale = 'en-US') {
  const rules = new Intl.PluralRules(locale);
  const category = rules.select(count);

  const messages = {
    'en-US': {
      one: `${count} item selected`,
      other: `${count} items selected`
    },
    'ko-KR': {
      other: `${count}개 항목이 선택됨` // 한국어는 복수 구분이 없어 'other'만 존재
    }
  };

  return messages[locale]?.[category] ?? messages[locale]?.other;
}

console.log(getMessage(1, 'en-US')); // "1 item selected"
console.log(getMessage(4, 'en-US')); // "4 items selected"
console.log(getMessage(4, 'ko-KR')); // "4개 항목이 선택됨"

const team = ['Alice', 'Bob', 'Charlie'];

// 접속(conjunction): 기본형 (A, B and C)
const listKo = new Intl.ListFormat('ko-KR', { style: 'long', type: 'conjunction' });
const listEn = new Intl.ListFormat('en-US', { style: 'long', type: 'conjunction' });

console.log(listKo.format(team)); // "Alice, Bob 및 Charlie"
console.log(listEn.format(team)); // "Alice, Bob, and Charlie" (옥스퍼드 콤마 자동 적용)

// 분리(disjunction): 또는 (A, B or C)
const disjEn = new Intl.ListFormat('en-US', { style: 'short', type: 'disjunction' });
console.log(disjEn.format(team)); // "Alice, Bob, or Charlie"

const words = ['ä', 'z', 'a'];

// 기본 sort (ASCII 순 정렬)
console.log([...words].sort()); // ['a', 'z', 'ä'] -> 독일어 기준 잘못된 순서

// 독일어 Collator 사용 정렬
const collatorDe = new Intl.Collator('de');
console.log([...words].sort(collatorDe.compare)); // ['a', 'ä', 'z'] -> 올바른 사전 순서

// 대소문자 무시 및 숫자 크기 인식 정렬
const files = ['file10.txt', 'file2.txt', 'file1.txt'];
const naturalSort = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
console.log(files.sort(naturalSort.compare)); // ['file1.txt', 'file2.txt', 'file10.txt']

const text = 'こんにちは世界！Intl APIを学びます。';
const segmenter = new Intl.Segmenter('ja-JP', { granularity: 'word' });

const segments = Array.from(segmenter.segment(text));
console.log(segments.filter(s => s.isWordLike).map(s => s.segment));
// ['こんにちは', '世界', 'Intl', 'API', 'を', '学び', 'ます']

const emoji = '👨‍👩‍👧‍👦';
console.log(emoji.length); // 11 (UTF-16 코드 유닛)

const graphemeSegmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
console.log([...graphemeSegmenter.segment(emoji)].length); // 1 (실제 보이는 글자 1개)

const regionNames = new Intl.DisplayNames(['ko-KR'], { type: 'region' });
console.log(regionNames.of('US')); // "미국"
console.log(regionNames.of('FR')); // "프랑스"

const langNames = new Intl.DisplayNames(['ko-KR'], { type: 'language' });
console.log(langNames.of('es')); // "스페인어"

const currencyNames = new Intl.DisplayNames(['ko-KR'], { type: 'currency' });
console.log(currencyNames.of('JPY')); // "일본 엔"

// Intl.DurationFormat (ECMAScript 최신 표준)
if ('DurationFormat' in Intl) {
  const durationFormat = new Intl.DurationFormat('ko-KR', { style: 'long' });
  console.log(durationFormat.format({
    hours: 2,
    minutes: 45,
    seconds: 10
  }));
  // "2시간 45분 10초"
}

const amount = 12500.5;
const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

const parts = formatter.formatToParts(amount);
console.log(parts);
/*
[
  { type: 'currency', value: '$' },
  { type: 'integer', value: '12' },
  { type: 'group', value: ',' },
  { type: 'integer', value: '500' },
  { type: 'decimal', value: '.' },
  { type: 'fraction', value: '50' }
]
*/

function PriceTag({ value, currency = 'USD', locale = 'en-US' }) {
  const formatter = new Intl.NumberFormat(locale, { style: 'currency', currency });
  const parts = formatter.formatToParts(value);

  return (
    <span className="price-container">
      {parts.map((part, index) => {
        if (part.type === 'currency') {
          return <span key={index} className="text-xs text-gray-500">{part.value}</span>;
        }
        if (part.type === 'fraction') {
          return <sup key={index} className="text-sm text-blue-600">{part.value}</sup>;
        }
        return <span key={index} className="font-bold text-lg">{part.value}</span>;
      })}
    </span>
  );
}

// ❌ 수만 개의 데이터를 순회할 때마다 인스턴스를 생성함
const list = getBigDataList(); // 10,000건
const formatted = list.map(item => {
  const nf = new Intl.NumberFormat('ko-KR', { style: 'currency', currency: 'KRW' });
  return nf.format(item.price);
});

// ⭕ 인스턴스를 루프 바깥에서 단 한 번만 생성하거나 캐시 객체를 운용
const krwFormatter = new Intl.NumberFormat('ko-KR', { style: 'currency', currency: 'KRW' });
const formatted = list.map(item => krwFormatter.format(item.price));

const formatterCache = new Map();

function getNumberFormatter(locale, options = {}) {
  const key = `${locale}-${JSON.stringify(options)}`;
  if (!formatterCache.has(key)) {
    formatterCache.set(key, new Intl.NumberFormat(locale, options));
  }
  return formatterCache.get(key);
}

# Node.js가 full-icu를 지원하는지 확인하는 명령
node -e "console.log(new Intl.DateTimeFormat('ko-KR', { month: 'long' }).format(new Date()))"
# 출력 결과가 "10월"이 아니라 "October"로 나온다면 full-icu가 빠져 있는 상태입니다.

// ❌ 서버 환경과 브라우저 환경의 로케일 불일치로 Hydration Mismatch 유발
export default function Price({ amount }) {
  const formatted = new Intl.NumberFormat(navigator.language).format(amount);
  return <div>{formatted}</div>;
}