작가:
    생성:2025-09-04마지막 업데이트:2026-06-23

    Intlayer로 React Router v7 번역하기 | 국제화(i18n)

    이 가이드는 React Router v7 프로젝트에서 로케일 인식 라우팅, TypeScript 지원 및 최신 개발 방식을 활용하여 Intlayer를 통합해 원활한 국제화(i18n)를 구현하는 방법을 보여줍니다.

    클라이언트 사이드 라우팅의 경우 Intlayer와 React Router v7 가이드를 참조하세요.

    목차

    대안보다 Intlayer를 선택해야 하는 이유는 무엇입니까?

    'react-i18next' 또는 'i18next'와 같은 주요 솔루션과 비교할 때 Intlayer는 다음과 같은 통합 최적화가 제공되는 솔루션입니다.

    Intlayer는 로케일 인식 라우팅, 로케일 감지를 위한 미들웨어 및 국제화 확장(i18n)에 필요한 모든 기능을 제공하여 React Router와 완벽하게 작동하도록 최적화되었습니다.

    대용량 JSON 파일을 페이지에 로드하는 대신 필요한 콘텐츠만 로드하세요. Intlayer는 번들 및 페이지 크기를 최대 50% 줄이는 데 도움이 됩니다.

    애플리케이션 콘텐츠의 범위를 지정하면 대규모 애플리케이션의 유지 관리가 용이해집니다. 전체 콘텐츠 코드베이스를 검토해야 하는 정신적 부담 없이 단일 기능 폴더를 복제하거나 삭제할 수 있습니다. 또한 Intlayer는 완전히 유형되어 콘텐츠의 정확성을 보장합니다.

    콘텐츠를 같은 위치에 배치하면 LLM(대형 언어 모델)에 필요한 컨텍스트가 줄어듭니다. Intlayer에는 누락된 번역을 테스트하기 위한 CLI, LSP, MCP 및 agent)와 같은 도구 모음도 함께 제공됩니다. 기술, AI 에이전트를 위한 개발자 경험(DX)을 더욱 원활하게 만듭니다.

    AI 공급자의 비용으로 선택한 LLM을 사용하여 CI/CD 파이프라인을 번역하려면 자동화를 사용하세요. Intlayer는 또한 콘텐츠 추출을 자동화하는 컴파일러와 백그라운드에서 번역을 돕는 웹 플랫폼을 제공합니다.

    대규모 JSON 파일을 구성 요소에 연결하면 성능 및 반응성 문제가 발생할 수 있습니다. Intlayer는 빌드 시 콘텐츠 로딩을 최적화합니다.

    Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는 자체 호스팅 비주얼 편집기 및 전체 CMS를 제공합니다. 다국어 콘텐츠를 실시간으로 제공하여 번역가, 카피라이터, 기타 팀원과 원활하게 협업할 수 있습니다. 콘텐츠는 로컬 및/또는 원격으로 저장될 수 있습니다.

    React Router v7 애플리케이션에서 Intlayer 설정 단계별 가이드

    1. 의존성 설치

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

      bash
      npx intlayer-cli init --interactive
      --interactive 플래그는 선택 사항입니다. AI 에이전트인 경우 intlayer-cli init를 사용하세요.
      이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
      bash
      npm install intlayer react-intlayernpm install vite-intlayer --save-dev

      • intlayer

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

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

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

    2. 프로젝트 구성

    파일 구조

    bash
    app/├── root.tsx                         # 로케일 경로를 위한 레이아웃 래퍼└──routes/    ├── ($locale)._index.tsx         # 홈 페이지 (/, /es, 등)    ├── ($locale)._index.content.ts  # 홈 페이지 콘텐츠    ├── ($locale).about.tsx          # About 페이지 (/about, /es/about, 등)    └── ($locale).about.content.ts   # About 페이지 콘텐츠

    명명 규칙:

    • ($locale) - 로케일 파라미터를 위한 선택적 동적 세그먼트
    • _layout - 자식 경로를 래핑하는 레이아웃 경로
    • _index - 인덱스 경로 (부모 경로에서 렌더링)
    • . (점) - 경로 세그먼트 구분 (예: ($locale).about → /:locale?/about)

    파일 시스템 기반 라우트를 사용한 React Router v7 애플리케이션에서 Intlayer 설정을 위한 단계별 가이드

    www.youtube.com

    See Application Template on GitHub.

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

    intlayer.config.ts
    import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH, // 기본 로케일 설정
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], // 지원하는 로케일 목록
  },
};

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

    1. Vite 구성에 Intlayer 통합하기

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

      vite.config.ts
      import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [reactRouter(), intlayer()],});
      intlayer() Vite 플러그인은 Intlayer를 Vite와 통합하는 데 사용됩니다. 이 플러그인은 콘텐츠 선언 파일의 빌드를 보장하고 개발 모드에서 이를 모니터링합니다. 또한 Vite 애플리케이션 내에서 Intlayer 환경 변수를 정의하며, 성능 최적화를 위한 별칭(alias)도 제공합니다.

    1. React Router v7 라우트 구성

      로케일 인식 라우트로 라우팅 구성을 설정하세요:

      app/routes.ts
      import { layout, route, type RouteConfig } from "@react-router/dev/routes";export default [  layout("routes/layout.tsx", [    route("/:lang?", "routes/page.tsx"), // 지역화된 홈 페이지    route("/:lang?/about", "routes/about/page.tsx"), // 지역화된 소개 페이지  ]),] satisfies RouteConfig;

    2. 컴포넌트 콘텐츠 추출

      선택사항

      기존 코드베이스가 있는 경우 수천 개의 파일을 변환하는 데 시간이 많이 걸릴 수 있습니다.

      이 프로세스를 용이하게 하기 위해 Intlayer는 컴포넌트를 변환하고 콘텐츠를 추출하기 위한 컴파일러 / 추출기를 제안합니다.

      설정하려면 intlayer.config.ts 파일에 compiler 섹션을 추가할 수 있습니다.

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... 나머지 구성
  compiler: {
    /**
     * 컴파일러 활성화 여부를 나타냅니다.
     */
    enabled: true,

    /**
     * 출력 파일 경로를 정의합니다.
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * 변환 후 컴포넌트를 저장할지 여부를 나타냅니다. 그렇게 하면 컴파일러를 한 번만 실행하여 앱을 변환한 다음 제거할 수 있습니다.
     */
    saveComponents: false,

    /**
     * 사전 키 접두사
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      컴포넌트를 변환하고 콘텐츠를 추출하기 위해 추출기를 실행합니다

      bash
      npx intlayer extract

    3. 레이아웃 컴포넌트 생성

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

      루트 레이아웃

      app/routes/layout.tsx
      import { IntlayerProvider } from "react-intlayer";import { Outlet } from "react-router";import type { Route } from "./+types/layout";export default function RootLayout({ params }: Route.ComponentProps) {  const { locale } = params;  return (    <IntlayerProvider locale={locale}>      <Outlet />    </IntlayerProvider>  );}

    4. 콘텐츠 선언하기

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

      app/routes/[lang]/page.content.ts
      import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    title: t({      en: "Welcome to React Router v7 + Intlayer",      es: "Bienvenido a React Router v7 + Intlayer",      fr: "Bienvenue sur React Router v7 + Intlayer",    }),    description: t({      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",      es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",    }),    aboutLink: t({      en: "Learn About Us",      es: "Aprender Sobre Nosotros",      fr: "En savoir plus sur nous",    }),    homeLink: t({      en: "Home",      es: "Inicio",      fr: "Accueil",    }),  },} satisfies Dictionary;export default pageContent;
      콘텐츠 선언은 애플리케이션 내 어디서든 정의할 수 있으며, contentDir 디렉토리(기본값: ./app)에 포함되면 자동으로 인식됩니다. 또한 콘텐츠 선언 파일 확장자(기본값: .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml})와 일치해야 합니다.
      자세한 내용은 콘텐츠 선언 문서를 참조하세요.

    5. 로케일 인식 컴포넌트 생성

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

      app/components/localized-link.tsx
      import type { FC } from "react";import { getLocalizedUrl, type LocalesValues } from "intlayer";import { useLocale } from "react-intlayer";import { Link, type LinkProps, type To } from "react-router";const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);// 외부 링크인지 확인하는 함수export const locacalizeTo = (to: To, locale: LocalesValues): To => {  if (typeof to === "string") {    if (isExternalLink(to)) {      return to; // 외부 링크면 그대로 반환    }    return getLocalizedUrl(to, locale); // 내부 링크면 로케일에 맞게 변환  }  if (isExternalLink(to.pathname ?? "")) {    return to; // 외부 링크면 그대로 반환  }  return {    ...to,    pathname: getLocalizedUrl(to.pathname ?? "", locale), // 내부 경로를 로케일에 맞게 변환  };};export const LocalizedLink: FC<LinkProps> = (props) => {  const { locale } = useLocale();  return <Link {...props} to={locacalizeTo(props.to, locale)} />;};

      로컬라이즈된 경로로 이동하려는 경우, useLocalizedNavigate 훅을 사용할 수 있습니다:

      app/hooks/useLocalizedNavigate.ts
      import { useLocale } from "react-intlayer";import { type NavigateOptions, type To, useNavigate } from "react-router";import { locacalizeTo } from "~/components/localized-link";export const useLocalizedNavigate = () => {  const navigate = useNavigate();  const { locale } = useLocale();  const localizedNavigate = (to: To, options?: NavigateOptions) => {    const localedTo = locacalizeTo(to, locale);    navigate(localedTo, options);  };  return localizedNavigate;};

    6. 페이지에서 Intlayer 활용하기

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

      현지화된 홈 페이지

      app/routes/[lang]/page.tsx
      import { useIntlayer } from "react-intlayer";import { LocalizedLink } from "~/components/localized-link";export default function Page() {  const { title, description, aboutLink } = useIntlayer("page");  return (    <div>      <h1>{title}</h1>      <p>{description}</p>      <nav>        <LocalizedLink to="/about">{aboutLink}</LocalizedLink>      </nav>    </div>  );}
      useIntlayer 훅에 대해 더 알아보려면 문서를 참조하세요.

    7. 로케일 스위처 컴포넌트 만들기

      사용자가 언어를 변경할 수 있도록 컴포넌트를 만드세요:

      app/components/locale-switcher.tsx
      import type { FC } from "react";import {  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,  getPathWithoutLocale,  Locales,} from "intlayer";import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";import { Link, useLocation } from "react-router";export const LocaleSwitcher: FC = () => {  const { localeSwitcherLabel } = useIntlayer("locale-switcher");  const { pathname } = useLocation();  const { availableLocales, locale } = useLocale();  const pathWithoutLocale = getPathWithoutLocale(pathname);  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <Link            aria-current={localeItem === locale ? "page" : undefined}            aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}            onClick={() => setLocale(localeItem)}            to={getLocalizedUrl(pathWithoutLocale, localeItem)}          >            <span>              {/* 로케일 - 예: FR */}              {localeItem}            </span>            <span>              {/* 해당 로케일의 언어 - 예: Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* 현재 로케일에서의 언어 - 예: 현재 로케일이 Locales.SPANISH일 때 Francés */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* 영어로 된 언어 이름 - 예: French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </Link>        </li>      ))}    </ol>  );};
      useLocale 훅에 대해 더 알아보려면 문서를 참조하세요.

    8. HTML 속성 관리 추가 (선택 사항)

      선택사항

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

      app/hooks/useI18nHTMLAttributes.tsx
      import { 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]);};

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

      app/routes/layout.tsx
      import { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // 훅을 가져옵니다export default function RootLayout() {  useI18nHTMLAttributes(); // 훅을 호출합니다  return (    <IntlayerProvider>      <Outlet />    </IntlayerProvider>  );}

    Configure TypeScript

    Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

    Ensure your TypeScript configuration includes the autogenerated types:

    tsconfig.json
    {  // ... your existing configurations  include: [    // ... your existing includes    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

    Git Configuration

    It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

    To do this, you can add the following instructions to your .gitignore file:

    .gitignore
    # Intlayer에서 생성된 파일 무시.intlayer

    VS Code Extension

    To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

    Install from the VS Code Marketplace

    This extension provides:

    • Autocompletion for translation keys.
    • Real-time error detection for missing translations.
    • Inline previews of translated content.
    • Quick actions to easily create and update translations.

    For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

    Go Further

    To go further, you can implement the visual editor or externalize your content using the CMS.

    문서 참조

    이 포괄적인 가이드는 Intlayer를 React Router v7과 통합하여 로케일 인식 라우팅과 TypeScript 지원이 포함된 완전한 국제화 애플리케이션을 구축하는 데 필요한 모든 것을 제공합니다.

    React Router v7
    Compiler