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

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

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

    이 가이드는 프론트엔드 라우팅에 중점을 둡니다. fs-routes 라우팅의 경우 Intlayer with React Router v7 File-System Routes 가이드를 참조하세요.

    목차

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

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

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

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

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

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

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

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

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

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

    1. 의존성 설치

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

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

      • intlayer

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

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

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

    2. 프로젝트 구성

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

    www.youtube.com
    ide.intlayer.org
    intlayer-react-router-v7.vercel.app

    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 통합하기

      2. 구성에 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 [
  route("/:lang?", "routes/page.tsx"), // 지역화된 홈 페이지
  route("/:lang?/about", "routes/about/page.tsx"), // 지역화된 소개 페이지
] satisfies RouteConfig;

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

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

    루트 레이아웃

    app/root.tsx
    import { getLocaleFromPath } from "intlayer";
import { IntlayerProvider } from "react-intlayer";
import {
  data,
  Meta,
  Scripts,
  ScrollRestoration,
  useLoaderData,
} from "react-router";
import type { Route } from "./+types/root";

// ... Unchanged App, links and ErrorBoundary code

export async function loader({ request }: Route.LoaderArgs) {
  const locale = getLocaleFromPath(request.url);

  if (!locale) {
    throw data("Language not supported", { status: 404 });
  }

  return { locale };
}

export function Layout({
  children,
}: { children: React.ReactNode } & Route.ComponentProps) {
  const data = useLoaderData<typeof loader>();
  const { locale } = data ?? {};

  return (
    <html lang={locale}>
      <head>
        <meta charSet="utf-8" />
        <meta content="width=device-width, initial-scale=1" name="viewport" />
        <Meta />
        <Links />
      </head>
      <body>
        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

  3. 콘텐츠 선언하기

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

    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})와 일치해야 합니다.
    자세한 내용은 콘텐츠 선언 문서를 참조하세요.

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

    로케일 인식 내비게이션을 위한 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;
};

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

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

    현지화된 홈 페이지

    app/routes/page.tsx
    import { getIntlayer, validatePrefix } from "intlayer";
import { useIntlayer } from "react-intlayer";
import { data } from "react-router";

import { LocaleSwitcher } from "~/components/locale-switcher";

import { Navbar } from "~/components/navbar";
import type { Route } from "./+types/page";

export const loader = ({ params }: Route.LoaderArgs) => {
  const { locale } = params;

  const { isValid } = validatePrefix(locale);

  if (!isValid) {
    throw data("Locale not supported", { status: 404 });
  }
};

export const meta: Route.MetaFunction = ({ params }) => {
  const content = getIntlayer("page", params.locale);

  return [
    { title: content.title },
    { content: content.description, name: "description" },
  ];
};

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 훅에 대해 더 알아보려면 문서를 참조하세요.
    기존 앱이 있다면, Intlayer Compiler와 extract 명령어를 사용하여 수천 개의 컴포넌트를 몇 초 안에 변환할 수 있습니다.

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

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

    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 훅에 대해 더 알아보려면 문서를 참조하세요.

  7. 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>
  );
}

  8. 미들웨어 추가

    intlayerProxy를 사용하여 애플리케이션에 서버 측 라우팅을 추가할 수도 있습니다. 이 플러그인은 URL을 기반으로 현재 로케일을 자동으로 감지하고 적절한 로케일 쿠키를 설정합니다. 로케일이 지정되지 않으면 플러그인이 사용자의 브라우저 언어 기본 설정을 기반으로 가장 적절한 로케일을 결정합니다. 로케일이 감지되지 않으면 기본 로케일로 리다이렉트됩니다.

    intlayerProxy를 프로덕션에서 사용하려면 vite-intlayer 패키지를 devDependencies에서 dependencies로 변경해야 합니다.
    Intlayer v9부터 intlayerProxy()는 intlayer() 플러그인에 직접 번들로 포함되어 있으며 routing.enableProxy 옵션(true가 기본값)을 통해 기본적으로 활성화됩니다. 아래와 같이 따로 등록하는 것은 이제 선택 사항입니다. 이는 하위 호환성을 유지하고 플러그인 순서를 제어해야 하는 설정을 위해 유지됩니다. routing.enableProxy: false로 설정하여 거절할 수 있습니다. v9 릴리스 노트를 참조하세요.
    vite.config.ts
    import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

  9. 컴포넌트에서 콘텐츠 추출

    선택사항

    기존 codebase가 있는 경우, 수천 개의 파일을 변환하는 것은 시간이 많이 걸릴 수 있습니다.

    이 과정을 쉽게 하기 위해 Intlayer는 컴포넌트를 변환하고 콘텐츠를 추출하는 compiler / extractor를 제공합니다.

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

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

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

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

    /**
     * 변환 후 컴포넌트를 저장할지 여부를 나타냅니다.
     *
     * - `true`인 경우, 컴파일러는 디스크의 컴포넌트 파일을 재작성합니다. 따라서 변환은 영구적이며, 컴파일러는 다음 프로세스에서 변환을 건너뜁니다. 이렇게 하면 컴파일러는 앱을 변환한 다음 제거할 수 있습니다.
     *
     * - `false`인 경우, 컴파일러는 빌드 출력에만 `useIntlayer()` 함수 호출을 주입하고 기본 codebase를 유지합니다. 변환은 메모리에서만 수행됩니다.
     */
    saveComponents: false,

    /**
     * 딕셔너리 키 접두사
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

    extractor를 실행하여 컴포넌트를 변환하고 콘텐츠를 추출합니다

    bash
    npx intlayer extract
    v9부터 intlayerCompiler는 intlayer 플러그인에 포함되어 있습니다. 따라서 수동으로 추가할 필요가 없습니다.

    vite.config.ts를 업데이트하여 intlayerCompiler 플러그인을 포함하세요:

    vite.config.ts
    import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // compiler plugin을 추가합니다
  ],
});
    bash
    npm run build # 또는 npm run dev

    10. </Steps>

    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 지원이 포함된 완전한 국제화 애플리케이션을 구축하는 데 필요한 모든 것을 제공합니다.

    Vite 및 ReactReact Router v7 (fs-routes)