Intlayer의 향후 출시 예정에 대한 알림을 받으세요
    작가: AydinTheFirst
    생성:2025-09-09마지막 업데이트:2025-09-09

    Intlayer와 Tanstack Start로 시작하는 국제화(i18n)

    이 가이드는 Tanstack Start 프로젝트에서 로케일 인식 라우팅, TypeScript 지원 및 최신 개발 방식을 활용하여 Intlayer를 원활하게 통합하는 방법을 보여줍니다.

    Intlayer란 무엇인가요?

    Intlayer는 현대 웹 애플리케이션에서 다국어 지원을 간소화하기 위해 설계된 혁신적이고 오픈 소스인 국제화(i18n) 라이브러리입니다.

    Intlayer를 사용하면 다음을 할 수 있습니다:

    • 컴포넌트 수준에서 선언적 사전을 사용하여 번역을 쉽게 관리할 수 있습니다.
    • 메타데이터, 라우트 및 콘텐츠를 동적으로 현지화할 수 있습니다.
    • 자동 생성된 타입으로 TypeScript 지원을 보장하여 자동 완성 및 오류 감지를 개선합니다.
    • 동적 로케일 감지 및 전환과 같은 고급 기능을 활용할 수 있습니다.
    • Tanstack Start의 파일 기반 라우팅 시스템을 사용하여 로케일 인식 라우팅 활성화.

    Tanstack Start 애플리케이션에서 Intlayer 설정 단계별 가이드

    1단계: 프로젝트 생성

    TanStack Start 웹사이트의 새 프로젝트 시작하기 가이드를 따라 새 TanStack Start 프로젝트를 생성합니다.

    2단계: Intlayer 패키지 설치

    선호하는 패키지 관리자를 사용하여 필요한 패키지를 설치합니다:

    bash
    npm install intlayer react-intlayernpm install vite-intlayer --save-dev
    • intlayer

    핵심 패키지로서 구성 관리, 번역, 콘텐츠 선언, 트랜스파일링 및 CLI 명령어를 위한 국제화 도구를 제공합니다.

    • react-intlayer
      Intlayer를 React 애플리케이션과 통합하는 패키지입니다. React 국제화를 위한 컨텍스트 프로바이더와 훅을 제공합니다.

    • vite-intlayer
      Intlayer를 Vite 번들러와 통합하기 위한 Vite 플러그인과, 사용자의 선호 로케일 감지, 쿠키 관리, URL 리디렉션 처리를 위한 미들웨어를 포함합니다.

    3단계: 프로젝트 구성

    애플리케이션의 언어를 구성하기 위한 설정 파일을 만드세요:

    intlayer.config.ts
    import type { IntlayerConfig } from "intlayer";import { Locales } from "intlayer";const config: IntlayerConfig = {  internationalization: {    defaultLocale: Locales.ENGLISH,    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // 다른 로케일들    ],  },};export default config;

    이 구성 파일을 통해 지역화된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언의 위치 및 확장자 설정, 콘솔에서 Intlayer 로그 비활성화 등 다양한 설정을 할 수 있습니다. 사용 가능한 모든 매개변수 목록은 구성 문서를 참조하세요.

    4단계: Vite 구성에 Intlayer 통합하기

    intlayer 플러그인을 구성에 추가하세요:

    vite.config.ts
    import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({  plugins: [    reactRouter(),    tsconfigPaths(),    intlayerPlugin(),    intlayerMiddlewarePlugin(),  ],});

    intlayerPlugin() Vite 플러그인은 Intlayer를 Vite와 통합하는 데 사용됩니다. 이 플러그인은 콘텐츠 선언 파일을 빌드하고 개발 모드에서 이를 모니터링합니다. 또한 Vite 애플리케이션 내에서 Intlayer 환경 변수를 정의하며, 성능 최적화를 위해 별칭(alias)도 제공합니다.

    5단계: 레이아웃 컴포넌트 생성

    루트 레이아웃과 로케일별 레이아웃을 설정하세요:

    루트 레이아웃

    src/routes/{-$locale}/route.tsx
    // src/routes/{-$locale}/route.tsximport { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";export const Route = createFileRoute("/{-$locale}")({  component: LayoutComponent,});function LayoutComponent() {  const { locale } = Route.useParams();  return (    <IntlayerProvider locale={locale}>      <Outlet />    </IntlayerProvider>  );}

    6단계: 콘텐츠 선언하기

    번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리하세요:

    src/contents/page.content.ts
    import type { Dictionary } from "intlayer";import { t } from "intlayer";const appContent = {  content: {    links: {      about: t({        en: "About",        es: "Acerca de",        fr: "À propos",      }),      home: t({        en: "홈",        es: "Inicio",        fr: "Accueil",      }),    },    meta: {      description: t({        en: "이것은 TanStack Router와 함께 Intlayer를 사용하는 예제입니다",        es: "Este es un ejemplo de uso de Intlayer con TanStack Router",        fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router",      }),    },    title: t({      en: "Intlayer + TanStack Router에 오신 것을 환영합니다",      es: "Bienvenido a Intlayer + TanStack Router",      fr: "Bienvenue à Intlayer + TanStack Router",    }),  },  key: "app",} satisfies Dictionary;export default appContent;

    콘텐츠 선언은 애플리케이션 내 어디에서든 정의할 수 있으며, contentDir 디렉토리(기본값은 ./app)에 포함되기만 하면 됩니다. 그리고 콘텐츠 선언 파일 확장자(기본값은 .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx})와 일치해야 합니다.

    자세한 내용은 콘텐츠 선언 문서를 참조하세요.

    7단계: 로케일 인식 컴포넌트 및 훅 생성

    로케일 인식 내비게이션을 위한 LocalizedLink 컴포넌트를 생성합니다:

    src/components/localized-link.tsx
    // src/components/localized-link.tsx// eslint-disable-next-line no-restricted-importsimport { Link, type LinkProps } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedLinkProps = {  to: string;} & Omit<LinkProps, "to">;export function LocalizedLink(props: LocalizedLinkProps) {  const { locale } = useLocale();  const isExternal = (to: string) => {    return /^(https?:)?\/\//.test(to);  };  const to = isExternal(props.to)    ? props.to    : getLocalizedUrl(props.to, locale);  return <Link {...props} to={to as LinkProps["to"]} />;}

    프로그래밍 방식 내비게이션을 위한 useLocalizedNavigate 훅을 생성하세요:

    src/hooks/useLocalizedNavigate.tsx
    // src/hooks/useLocalizedNavigate.tsx// eslint-disable-next-line no-restricted-importsimport { NavigateOptions, useNavigate } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedNavigateOptions = {  to: string;} & Omit<NavigateOptions, "to">;export const useLocalizedNavigate = () => {  const navigate = useNavigate();  const { locale } = useLocale();  const isExternal = (to: string) => {    return /^(https?:)?\/\//.test(to);  };  const localizedNavigate = (options: LocalizedNavigateOptions) => {    const to = isExternal(options.to)      ? options.to      : getLocalizedUrl(options.to, locale);    navigate({ ...options, to: to as NavigateOptions["to"] });  };  return localizedNavigate;};

    8단계: 페이지에서 Intlayer 사용하기

    애플리케이션 전반에서 콘텐츠 사전을 접근하세요:

    루트 리디렉션 페이지

    src/routes/page.tsx
    // src/routes/page.tsximport { useLocale } from "intlayer";import { Navigate } from "react-router";export default function Page() {  const { locale } = useLocale();  return <Navigate replace to={locale} />;}

    지역화된 홈 페이지

    src/routes/{-$locale}/index.tsx
    import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";import { useIntlayer } from "react-intlayer";import LocaleSwitcher from "@/components/locale-switcher";import { LocalizedLink } from "@/components/localized-link";import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";export const Route = createFileRoute("/{-$locale}/")({  component: RouteComponent,  head: ({ params }) => {    const { locale } = params;    const metaContent = getIntlayer("app", locale);    return {      meta: [        { title: metaContent.title },        { content: metaContent.meta.description, name: "description" },      ],    };  },});function RouteComponent() {  const content = useIntlayer("app");  const navigate = useLocalizedNavigate();  return (    <div className="grid place-items-center h-screen">      <div className="flex flex-col gap-4 items-center text-center">        {content.title}        <LocaleSwitcher />        <div className="flex gap-4">          <a href="/">인덱스</a>          <LocalizedLink to="/">{content.links.home}</LocalizedLink>          <LocalizedLink to="/about">{content.links.about}</LocalizedLink>        </div>        <div className="flex gap-4">          <button onClick={() => navigate({ to: "/" })}>            {content.links.home}          </button>          <button onClick={() => navigate({ to: "/about" })}>            {content.links.about}          </button>        </div>      </div>    </div>  );}

    useIntlayer 훅에 대해 더 알아보려면 문서를 참조하세요.

    9단계: 로케일 스위처 컴포넌트 만들기

    사용자가 언어를 변경할 수 있도록 컴포넌트를 만듭니다:

    src/components/locale-switcher.tsx
    import { useLocation } from "@tanstack/react-router";import {  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,  Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";export default function LocaleSwitcher() {  const { pathname, searchStr } = useLocation();  const content = useIntlayer("locale-switcher");  const { availableLocales, locale, setLocale } = useLocale({    onLocaleChange: (newLocale) => {      const pathWithLocale = getLocalizedUrl(pathname + searchStr, newLocale);      location.replace(pathWithLocale); // 새로운 로케일 경로로 페이지를 대체합니다.    },  });  return (    <select      aria-label={content.label.toString()} // 접근성을 위한 라벨      onChange={(e) => setLocale(e.target.value)} // 선택된 로케일로 변경      value={locale} // 현재 선택된 로케일 값    >      {availableLocales.map((localeItem) => (        <option          dir={getHTMLTextDir(localeItem)}          key={localeItem}          lang={localeItem}          value={localeItem}        >          {/* 예시: Français (프랑스어) */}          {getLocaleName(localeItem, locale)} (          {getLocaleName(localeItem, Locales.ENGLISH)})        </option>      ))}    </select>  );}

    useLocale 훅에 대해 더 알아보려면 문서를 참조하세요.

    10단계: HTML 속성 관리 추가 (선택 사항)

    HTML lang 및 dir 속성을 관리하는 훅을 만듭니다:

    src/hooks/useI18nHTMLAttributes.tsx
    // src/hooks/useI18nHTMLAttributes.tsximport { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  }, [locale]);};

    그런 다음 루트 컴포넌트에서 사용하세요:

    src/routes/{-$locale}/index.tsx
    import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // 훅을 임포트합니다.export const Route = createFileRoute("/{-$locale}")({  component: LayoutComponent,});function LayoutComponent() {  useI18nHTMLAttributes(); // 이 줄을 추가하세요  const { locale } = Route.useParams();  return (    <IntlayerProvider locale={locale}>      <Outlet />    </IntlayerProvider>  );}

    11단계: 애플리케이션 빌드 및 실행

    콘텐츠 사전을 빌드하고 애플리케이션을 실행하세요:

    bash
    # Intlayer 사전 빌드npm run intlayer:build# 개발 서버 시작npm run dev

    12단계: TypeScript 구성 (선택 사항)

    Intlayer는 TypeScript의 이점을 활용하고 코드베이스를 더욱 견고하게 만들기 위해 모듈 확장을 사용합니다.

    TypeScript 구성에 자동 생성된 타입이 포함되어 있는지 확인하세요:

    tsconfig.json
    {  compilerOptions: {    // ... 기존 TypeScript 구성  },  include: [    // ... 기존 포함 항목    ".intlayer/**/*.ts", // 자동 생성된 타입 포함  ],}

    Git 구성

    Intlayer가 생성한 파일들은 Git 저장소에 커밋하지 않도록 무시하는 것이 권장됩니다.

    이를 위해 .gitignore 파일에 다음 내용을 추가할 수 있습니다:

    .gitignore
    # Intlayer가 생성한 파일 무시.intlayer

    13단계: 리디렉션 생성 (선택 사항)

    src/routes/{-$locale}/rotue.tsx
    function LayoutComponent() {  useI18nHTMLAttributes();  const { locale } = Route.useParams();  const { locale: selectedLocale } = useLocale();  const { defaultLocale } = configuration.internationalization;  const { prefixDefault } = configuration.middleware;  // prefixDefault가 true일 때 URL에 로케일이 없으면 기본 로케일로 리디렉션  if (selectedLocale === defaultLocale && !locale && prefixDefault) {    return <Navigate replace to={defaultLocale} />;  }  // URL의 로케일이 선택된 로케일과 다르면 선택된 로케일로 리디렉션  if (selectedLocale !== defaultLocale && !locale) {    return <Navigate replace to={selectedLocale} />;  }  return (    <IntlayerProvider locale={locale}>      <Outlet />    </IntlayerProvider>  );}

    프로덕션 배포

    애플리케이션을 배포할 때:

    1. 애플리케이션 빌드:

      bash
      npm run build
    2. Intlayer 사전 빌드:

      bash
      npm run intlayer:build
    3. 프로덕션에서 미들웨어를 사용하는 경우 vite-intlayer를 dependencies로 이동:

      bash
      npm install vite-intlayer --save

    이제 애플리케이션은 다음을 지원합니다:

    • URL 구조: /en, /en/about, /tr, /tr/about
    • 브라우저 환경설정을 기반으로 한 자동 로케일 감지
    • Tanstack Start를 이용한 로케일 인식 라우팅
    • 자동 생성 타입을 포함한 TypeScript 지원
    • 적절한 로케일 처리를 포함한 서버 사이드 렌더링

    VS 코드 확장 기능

    Intlayer 개발 경험을 향상시키기 위해 공식 Intlayer VS Code 확장 프로그램을 설치할 수 있습니다.

    VS Code 마켓플레이스에서 설치하기

    이 확장 프로그램은 다음을 제공합니다:

    • 번역 키에 대한 자동 완성 기능.
    • 누락된 번역에 대한 실시간 오류 감지.
    • 번역된 콘텐츠의 인라인 미리보기.
    • 번역을 쉽게 생성하고 업데이트할 수 있는 빠른 작업.

    확장 프로그램 사용 방법에 대한 자세한 내용은 Intlayer VS Code 확장 프로그램 문서를 참조하세요.


    더 나아가기

    더 나아가려면 비주얼 에디터를 구현하거나 CMS를 사용하여 콘텐츠를 외부화할 수 있습니다.


    문서 참조

    이 종합 가이드는 지역 인식 라우팅과 TypeScript 지원을 갖춘 완전한 국제화 애플리케이션을 위해 Intlayer를 Tanstack Start와 통합하는 데 필요한 모든 것을 제공합니다.

    문서 이력

    버전 날짜 변경 사항
    5.8.1 2025-09-09 Tanstack Start용 추가됨
    Intlayer의 향후 출시 예정에 대한 알림을 받으세요