작가:
    Aymeric PINEAU
    생성:2025-07-27마지막 업데이트:2025-07-27

    로케일 매퍼

    로케일 매퍼는 Intlayer 애플리케이션에서 국제화 데이터를 다루는 데 도움을 주는 강력한 유틸리티입니다. 로케일별 데이터를 변환하고 조직하는 세 가지 주요 함수인 localeMap, localeFlatMap, localeRecord를 제공합니다.

    로케일 매퍼 작동 방식

    로케일 매퍼는 로케일에 관한 모든 필요한 정보를 포함하는 LocaleData 객체를 기반으로 작동합니다:

    typescript
    type LocaleData = {
  locale: LocalesValues; // 현재 로케일 코드 (예: 'en', 'fr')
  defaultLocale: LocalesValues; // 기본 로케일 코드
  isDefault: boolean; // 이 로케일이 기본 로케일인지 여부
  locales: LocalesValues[]; // 사용 가능한 모든 로케일 배열
  urlPrefix: string; // 이 로케일의 URL 접두사 (예: '/fr' 또는 '')
};

    매퍼 함수는 구성에 있는 각 로케일에 대해 이 데이터를 자동으로 생성하며, 다음 사항을 고려합니다:

    • 구성된 로케일 목록
    • 기본 로케일 설정
    • 기본 로케일이 URL에 접두사로 붙어야 하는지 여부

    핵심 함수

    localeMap

    매퍼 함수를 사용하여 각 로케일을 단일 객체로 변환합니다.

    typescript
    localeMap<T>(
  mapper: (locale: LocaleData) => T,
  locales?: LocalesValues[],
  defaultLocale?: LocalesValues,
  prefixDefault?: boolean
): T[]

    예제: 라우트 객체 생성하기

    typescript
    import { localeMap } from "intlayer";

const routes = localeMap((localizedData) => ({
  path: localizedData.urlPrefix,
  name: localizedData.locale,
  isDefault: localizedData.isDefault,
  locales: localizedData.locales,
  defaultLocale: localizedData.defaultLocale,
}));

// 결과:
// [
//   { path: '/', name: 'en', isDefault: true, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
//   { path: '/fr', name: 'fr', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
//   { path: '/es', name: 'es', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' }
// ]

    localeFlatMap

    localeMap과 유사하지만, 매퍼 함수가 객체 배열을 반환하며 이 배열이 단일 배열로 평탄화됩니다.

    typescript
    localeFlatMap<T>(
  mapper: (locale: LocaleData) => T[],
  locales?: LocalesValues[],
  defaultLocale?: LocalesValues,
  prefixDefault?: boolean
): T[]

    예제: 로케일별로 여러 경로 생성하기

    typescript
    import { localeFlatMap } from "intlayer";

const routes = localeFlatMap((localizedData) => [
  {
    path: localizedData.urlPrefix,
    name: localizedData.locale,
    isDefault: localizedData.isDefault,
  },
  {
    path: `${localizedData.urlPrefix}/about`,
    name: `${localizedData.locale}-about`,
    isDefault: localizedData.isDefault,
  },
]);

// 결과:
// [
//   { path: '/', name: 'en', isDefault: true },
  { path: '/about', name: 'en-about', isDefault: true },
  { path: '/fr', name: 'fr', isDefault: false },
  { path: '/fr/about', name: 'fr-about', isDefault: false },
  { path: '/es', name: 'es', isDefault: false },
  { path: '/es/about', name: 'es-about', isDefault: false }
]

    localeRecord

    각 로케일이 키가 되고, 매퍼 함수에 의해 변환된 값을 매핑하는 레코드 객체를 생성합니다.

    typescript
    localeRecord<T>(
  mapper: (locale: LocaleData) => T,
  locales?: Locales[],
  defaultLocale?: Locales,
  prefixDefault?: boolean
): Record<Locales, T>

    예제: 번역 파일 로딩하기

    typescript
    import { localeRecord } from "intlayer";

const translations = localeRecord(({ locale }) =>
  require(`./translations/${locale}.json`)
);

// 결과:
// {
//   en: { welcome: 'Welcome', hello: 'Hello' },
//   fr: { welcome: 'Bienvenue', hello: 'Bonjour' },
//   es: { welcome: 'Bienvenido', hello: 'Hola' }
// }

    로케일 매퍼 설정하기

    로케일 매퍼는 자동으로 Intlayer 설정을 사용하지만, 매개변수를 전달하여 기본값을 재정의할 수 있습니다:

    기본 설정 사용하기

    typescript
    import { localeMap } from "intlayer";

// intlayer.config.ts의 설정을 사용합니다
const routes = localeMap((data) => ({
  path: data.urlPrefix,
  locale: data.locale,
}));

    설정 재정의하기

    typescript
    import { localeMap } from "intlayer";

// 로케일과 기본 로케일을 재정의합니다
const customRoutes = localeMap(
  (data) => ({ path: data.urlPrefix, locale: data.locale }),
  ["en", "fr", "de"], // 사용자 지정 로케일
  "en", // 사용자 지정 기본 로케일
  true // URL에 기본 로케일 접두사 추가
);

    고급 사용 예제

    내비게이션 메뉴 생성

    typescript
    import { localeMap } from "intlayer";

const navigationItems = localeMap((data) => ({
  label: data.locale.toUpperCase(), // 로케일을 대문자로 표시
  href: data.urlPrefix || "/", // URL 접두사 또는 기본 경로
  isActive: data.isDefault, // 기본 로케일 여부
  flag: `/flags/${data.locale}.svg`, // 로케일에 해당하는 국기 아이콘 경로
}));

    사이트맵 데이터 생성

    typescript
    import { localeFlatMap } from "intlayer";

const sitemapUrls = localeFlatMap((data) => [
  {
    url: `${data.urlPrefix}/`, // URL 경로
    lastmod: new Date().toISOString(), // 마지막 수정 날짜
    changefreq: "daily", // 변경 빈도
    priority: data.isDefault ? 1.0 : 0.8, // 우선순위
  },
  {
    url: `${data.urlPrefix}/about`,
    lastmod: new Date().toISOString(),
    changefreq: "monthly",
    priority: data.isDefault ? 0.8 : 0.6,
  },
]);

    동적 번역 로딩

    typescript
    import { localeRecord } from "intlayer";

const translationModules = localeRecord(({ locale }) => ({
  messages: import(`./locales/${locale}/messages.json`),
  validation: import(`./locales/${locale}/validation.json`),
  metadata: {
    locale,
    direction: ["ar", "he", "fa"].includes(locale) ? "rtl" : "ltr", // 오른쪽에서 왼쪽으로 읽는 언어인지 여부
  },
}));

    구성 통합

    Locale Mapper는 Intlayer 구성과 원활하게 통합됩니다:

    • Locales: configuration.internationalization.locales를 자동으로 사용합니다
    • 기본 로케일: configuration.internationalization.defaultLocale를 사용합니다
    • URL 접두사: configuration.middleware.prefixDefault를 준수합니다

    이것은 애플리케이션 전반에 걸쳐 일관성을 보장하고 구성 중복을 줄여줍니다.

    Intlayer의 이점