이 페이지와 원하는 AI 어시스턴트를 사용하여 문서를 요약합니다
Intlayer MCP 서버를 통해 ChatGPT, DeepSeek, Cursor, VSCode 등에서 직접 문서를 검색할 수 있습니다.
MCP 서버 문서 보기이 페이지의 콘텐츠는 AI를 사용하여 번역되었습니다.
영어 원본 내용의 최신 버전을 보기이 문서를 개선할 아이디어가 있으시면 GitHub에 풀 리퀘스트를 제출하여 자유롭게 기여해 주세요.
문서에 대한 GitHub 링크문서의 Markdown을 클립보드에 복사
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 패키지 설치
선호하는 패키지 관리자를 사용하여 필요한 패키지를 설치합니다:
코드를 클립보드에 복사
npm install intlayer react-intlayernpm install vite-intlayer --save-dev
- intlayer
핵심 패키지로서 구성 관리, 번역, 콘텐츠 선언, 트랜스파일링 및 CLI 명령어를 위한 국제화 도구를 제공합니다.
react-intlayer
Intlayer를 React 애플리케이션과 통합하는 패키지입니다. React 국제화를 위한 컨텍스트 프로바이더와 훅을 제공합니다.vite-intlayer
Intlayer를 Vite 번들러와 통합하기 위한 Vite 플러그인과, 사용자의 선호 로케일 감지, 쿠키 관리, URL 리디렉션 처리를 위한 미들웨어를 포함합니다.
3단계: 프로젝트 구성
애플리케이션의 언어를 구성하기 위한 설정 파일을 만드세요:
코드를 클립보드에 복사
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 플러그인을 구성에 추가하세요:
코드를 클립보드에 복사
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.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단계: 콘텐츠 선언하기
번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리하세요:
코드를 클립보드에 복사
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// 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// 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.tsximport { useLocale } from "intlayer";import { Navigate } from "react-router";export default function Page() { const { locale } = useLocale(); return <Navigate replace to={locale} />;}
지역화된 홈 페이지
코드를 클립보드에 복사
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단계: 로케일 스위처 컴포넌트 만들기
사용자가 언어를 변경할 수 있도록 컴포넌트를 만듭니다:
코드를 클립보드에 복사
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.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]);};
그런 다음 루트 컴포넌트에서 사용하세요:
코드를 클립보드에 복사
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단계: 애플리케이션 빌드 및 실행
콘텐츠 사전을 빌드하고 애플리케이션을 실행하세요:
코드를 클립보드에 복사
# Intlayer 사전 빌드npm run intlayer:build# 개발 서버 시작npm run dev
12단계: TypeScript 구성 (선택 사항)
Intlayer는 TypeScript의 이점을 활용하고 코드베이스를 더욱 견고하게 만들기 위해 모듈 확장을 사용합니다.
TypeScript 구성에 자동 생성된 타입이 포함되어 있는지 확인하세요:
코드를 클립보드에 복사
{ compilerOptions: { // ... 기존 TypeScript 구성 }, include: [ // ... 기존 포함 항목 ".intlayer/**/*.ts", // 자동 생성된 타입 포함 ],}
Git 구성
Intlayer가 생성한 파일들은 Git 저장소에 커밋하지 않도록 무시하는 것이 권장됩니다.
이를 위해 .gitignore 파일에 다음 내용을 추가할 수 있습니다:
코드를 클립보드에 복사
# Intlayer가 생성한 파일 무시.intlayer
13단계: 리디렉션 생성 (선택 사항)
코드를 클립보드에 복사
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> );}
프로덕션 배포
애플리케이션을 배포할 때:
애플리케이션 빌드:
bash코드 복사코드를 클립보드에 복사
npm run build
Intlayer 사전 빌드:
bash코드 복사코드를 클립보드에 복사
npm run intlayer:build
프로덕션에서 미들웨어를 사용하는 경우 vite-intlayer를 dependencies로 이동:
bash코드 복사코드를 클립보드에 복사
npm install vite-intlayer --save
이제 애플리케이션은 다음을 지원합니다:
- URL 구조: /en, /en/about, /tr, /tr/about
- 브라우저 환경설정을 기반으로 한 자동 로케일 감지
- Tanstack Start를 이용한 로케일 인식 라우팅
- 자동 생성 타입을 포함한 TypeScript 지원
- 적절한 로케일 처리를 포함한 서버 사이드 렌더링
VS 코드 확장 기능
Intlayer 개발 경험을 향상시키기 위해 공식 Intlayer VS Code 확장 프로그램을 설치할 수 있습니다.
이 확장 프로그램은 다음을 제공합니다:
- 번역 키에 대한 자동 완성 기능.
- 누락된 번역에 대한 실시간 오류 감지.
- 번역된 콘텐츠의 인라인 미리보기.
- 번역을 쉽게 생성하고 업데이트할 수 있는 빠른 작업.
확장 프로그램 사용 방법에 대한 자세한 내용은 Intlayer VS Code 확장 프로그램 문서를 참조하세요.
더 나아가기
더 나아가려면 비주얼 에디터를 구현하거나 CMS를 사용하여 콘텐츠를 외부화할 수 있습니다.
문서 참조
이 종합 가이드는 지역 인식 라우팅과 TypeScript 지원을 갖춘 완전한 국제화 애플리케이션을 위해 Intlayer를 Tanstack Start와 통합하는 데 필요한 모든 것을 제공합니다.
문서 이력
버전 | 날짜 | 변경 사항 |
---|---|---|
5.8.1 | 2025-09-09 | Tanstack Start용 추가됨 |