Getting Started internationalizing (i18n) with Intlayer and Next.js 15 App Router
Intlayer란 무엇인가요?
Intlayer는 현대 웹 애플리케이션에서 다국어 지원을 간소화하도록 설계된 혁신적인 오픈 소스 국제화 (i18n) 라이브러리입니다. Intlayer는 최신 Next.js 15 프레임워크와 원활하게 통합되며, 강력한 App Router를 포함합니다. 서버 구성 요소와 함께 효율적인 렌더링을 위해 최적화되었으며, Turbopack과 완전히 호환됩니다.
Intlayer를 사용하면:
- 선언적 사전을 사용하여 번역을 쉽게 관리할 수 있습니다.
- 메타데이터, 경로 및 콘텐츠를 동적으로 지역화할 수 있습니다.
- 클라이언트 측 및 서버 측 구성 요소에서 번역에 접근할 수 있습니다.
- 자동 생성된 타입으로 TypeScript 지원 보장, 자동 완성과 오류 감지를 개선합니다.
- 동적 지역 감지 및 전환과 같은 고급 기능의 혜택을 누릴 수 있습니다.
참고: Intlayer는 Next.js 12, 13, 14 및 15와 호환됩니다. Next.js 페이지 라우터를 사용하는 경우, 이 가이드를 참조할 수 있습니다. Next.js 12, 13, 14와 App Router의 경우, 이 가이드를 참조하세요.
Next.js 애플리케이션에서 Intlayer 설정을 위한 단계별 가이드
1단계: 종속성 설치
필요한 패키지를 npm을 사용해 설치하세요:
bash
1npm install intlayer next-intlayerbash
1yarn add intlayer next-intlayerbash
1pnpm add intlayer next-intlayer2단계: 프로젝트 구성
애플리케이션의 언어를 구성하기 위해 설정 파일을 생성하세요:
typescript
1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6 internationalization: {
7 locales: [
8 Locales.ENGLISH,
9 Locales.FRENCH,
10 Locales.SPANISH,
11 // 다른 지역 추가
12 ],
13 defaultLocale: Locales.ENGLISH,
14 },
15};
16
17export default config;사용 가능한 모든 매개변수를 보려면, 구성 문서 여기를 참조하세요.
3단계: Next.js 설정에서 Intlayer 통합
Next.js 설정을 Intlayer를 사용하도록 구성하세요:
typescript
1// next.config.mjs
2import { withIntlayer } from "next-intlayer/server";
3
4/** @type {import('next').NextConfig} */
5const nextConfig = {};
6
7export default withIntlayer(nextConfig);4단계: 로케일 감지를 위한 미들웨어 구성
사용자의 선호 로케일을 감지하기 위해 미들웨어를 설정하세요:
typescript
1// src/middleware.ts
2export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
3
4export const config = {
5 matcher: "/((?!api|static|.*\\..*|_next).*)",
6};5단계: 동적 로케일 경로 정의
지역화된 콘텐츠에 대한 동적 라우팅을 구현하세요:
src/app/page.ts를 src/app/[locale]/page.ts로 변경하세요.
그런 다음 애플리케이션 레이아웃에서 generateStaticParams 함수를 구현하세요.
tsx
1// src/app/layout.tsx
2
3import type { ReactNode } from "react";
4import "./globals.css";
5
6export { generateStaticParams } from "next-intlayer"; // 삽입할 줄
7
8const RootLayout = ({
9 children,
10}: Readonly<{
11 children: ReactNode;
12}>) => children;
13
14export default RootLayout;그런 다음 [locale] 디렉토리에 새로운 레이아웃을 추가하세요:
tsx
1// src/app/[locale]/layout.tsx
2
3import { type NextLayoutIntlayer } from "next-intlayer";
4import { Inter } from "next/font/google";
5import { getHTMLTextDir } from "intlayer";
6
7const inter = Inter({ subsets: ["latin"] });
8
9const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
10 const { locale } = await params;
11 return (
12 <html lang={locale} dir={getHTMLTextDir(locale)}>
13 <body className={inter.className}>{children}</body>
14 </html>
15 );
16};
17
18export default LocaleLayout;6단계: 콘텐츠 선언
콘텐츠 사전을 생성하고 관리하세요:
tsx
1// src/app/[locale]/page.content.ts
2import { t, type DeclarationContent } from "intlayer";
3
4const pageContent = {
5 key: "page",
6 content: {
7 getStarted: {
8 main: t({
9 en: "Get started by editing",
10 fr: "Commencez par éditer",
11 es: "Comience por editar",
12 }),
13 pageLink: "src/app/page.tsx",
14 },
15 },
16} satisfies DeclarationContent;
17
18export default pageContent;7단계: 코드에서 콘텐츠 활용
애플리케이션 전반에 걸쳐 콘텐츠 사전에 접근하세요:
tsx
1// src/app/[locale]/page.ts
2
3import { ClientComponentExample } from "@component/ClientComponentExample";
4import { LocaleSwitcher } from "@component/LangSwitcherDropDown";
5import { NestedServerComponentExample } from "@component/NestedServerComponentExample";
6import { ServerComponentExample } from "@component/ServerComponentExample";
7import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
8import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
9
10const PageContent = () => {
11 const { title, content } = useIntlayer("page");
12
13 return (
14 <>
15 <p>{content.getStarted.main}</p>
16 <code>{content.getStarted.pageLink}</code>
17 </>
18 );
19};
20
21const Page: NextPageIntlayer = async ({ params }) => {
22 const { locale } = await params;
23
24 return (
25 <>
26 {/**
27 * IntlayerServerProvider는 서버 자식에게 로케일을 제공하는 데 사용됩니다.
28 * 레이아웃에 설정하면 작동하지 않습니다.
29 */}
30 <IntlayerServerProvider locale={locale}>
31 <PageContent />
32 <ServerComponentExample />
33 </IntlayerServerProvider>
34 {/**
35 * IntlayerClientProvider는 클라이언트 자식에게 로케일을 제공하는 데 사용됩니다.
36 * 레이아웃을 포함하여 모든 부모 구성 요소에 설정할 수 있습니다.
37 */}
38 <IntlayerClientProvider locale={locale}>
39 <ClientComponentExample />
40 </IntlayerClientProvider>
41 </>
42 );
43};
44
45export default Page;tsx
1// src/components/ClientComponentExample.tsx
2
3"use client";
4
5import { useIntlayer } from "next-intlayer";
6
7export const ClientComponentExample = () => {
8 const content = useIntlayer("client-component-example"); // 관련 콘텐츠 선언 만들기
9
10 return (
11 <div>
12 <h2>{content.title} </h2>
13 <p>{content.content}</p>
14 </div>
15 );
16};tsx
1// src/components/ServerComponentExample.tsx
2
3import { useIntlayer } from "next-intlayer/server";
4
5export const ServerComponentExample = () => {
6 const content = useIntlayer("server-component-example"); // 관련 콘텐츠 선언 만들기
7
8 return (
9 <div>
10 <h2>{content.title} </h2>
11 <p>{content.content}</p>
12 </div>
13 );
14};참고: alt, title, href, aria-label와 같은 string 속성에서 콘텐츠를 사용하려면, 함수의 값으로 호출해야 합니다:
tsx1<img src={content.image.src.value} alt={content.image.value} />
클라이언트 또는 서버 구성 요소에서 intlayer를 사용하는 더 자세한 내용은 Next.js 예제 여기를 참조하세요.
(선택 사항) 8단계: 메타데이터 국제화
페이지의 제목과 같은 메타데이터를 국제화하려면, Next.js에서 제공하는 generateMetadata 함수를 사용할 수 있습니다. 함수 내에서 getTranslationContent 함수를 사용하여 메타데이터를 번역하세요.
typescript
1// src/app/[locale]/layout.tsx 또는 src/app/[locale]/page.tsx
2
3import {
4 type IConfigLocales,
5 getTranslationContent,
6 getMultilingualUrls,
7} from "intlayer";
8import type { Metadata } from "next";
9import type { LocalParams } from "next-intlayer";
10
11export const generateMetadata = ({
12 params: { locale },
13}: LocalParams): Metadata => {
14 const t = <T>(content: IConfigLocales<T>) =>
15 getTranslationContent(content, locale);
16
17 /**
18 * 각 로케일에 대한 모든 URL을 포함하는 개체를 생성합니다.
19 *
20 * 예시:
21 * ```ts
22 * getMultilingualUrls('/about');
23 *
24 * // 반환값
25 * // {
26 * // en: '/about',
27 * // fr: '/fr/about',
28 * // es: '/es/about',
29 * // }
30 * ```
31 */
32 const multilingualUrls = getMultilingualUrls("/");
33
34 return {
35 title: t<string>({
36 en: "My title",
37 fr: "Mon titre",
38 es: "Mi título",
39 }),
40 description: t({
41 en: "My description",
42 fr: "Ma description",
43 es: "Mi descripción",
44 }),
45 alternates: {
46 canonical: url,
47 languages: { ...multilingualUrls, "x-default": "/" },
48 },
49 openGraph: {
50 url: multilingualUrls[locale],
51 },
52 };
53};
54
55// ... 나머지 코드메타데이터 최적화에 대한 더 많은 정보는 공식 Next.js 문서를 참조하세요.
(선택 사항) 9단계: sitemap.xml 및 robots.txt의 국제화
sitemap.xml 및 robots.txt를 국제화하려면, Intlayer에서 제공하는 getMultilingualUrls 함수를 사용할 수 있습니다. 이 함수는 sitemap을 위한 다국어 URLs를 생성할 수 있게 합니다.
tsx
1// src/app/sitemap.ts
2
3import { getMultilingualUrls } from "intlayer";
4import type { MetadataRoute } from "next";
5
6const sitemap = (): MetadataRoute.Sitemap => [
7 {
8 url: "https://example.com",
9 alternates: {
10 languages: getMultilingualUrls("https://example.com"),
11 },
12 },
13 {
14 url: "https://example.com/login",
15 alternates: {
16 languages: getMultilingualUrls("https://example.com/login"),
17 },
18 },
19 {
20 url: "https://example.com/register",
21 alternates: {
22 languages: getMultilingualUrls("https://example.com/register"),
23 },
24 },
25];
26
27export default sitemap;tsx
1// src/app/robots.ts
2import type { MetadataRoute } from "next";
3import { getMultilingualUrls } from "intlayer";
4
5const getAllMultilingualUrls = (urls: string[]) =>
6 urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
7
8const robots = (): MetadataRoute.Robots => ({
9 rules: {
10 userAgent: "*",
11 allow: ["/"],
12 disallow: getAllMultilingualUrls(["/login", "/register"]),
13 },
14 host: "https://example.com",
15 sitemap: `https://example.com/sitemap.xml`,
16});
17
18export default robots;sitemap 최적화에 대한 더 많은 정보는 공식 Next.js 문서를 참조하세요. robots.txt 최적화에 대한 더 많은 정보는 공식 Next.js 문서를 참조하세요.
(선택 사항) 10단계: 콘텐츠 언어 변경
콘텐츠 언어를 변경하려면, useLocale 훅에서 제공하는 setLocale 함수를 사용할 수 있습니다. 이 함수는 애플리케이션의 로케일을 설정하고 콘텐츠를 적절히 업데이트할 수 있게 합니다.
tsx
1import { Locales } from "intlayer";
2import { useLocale } from "next-intlayer";
3
4const MyComponent = () => {
5 const { setLocale } = useLocale();
6
7 return <button onClick={() => setLocale(Locales.English)}>언어 변경</button>;
8};TypeScript 구성
Intlayer는 모듈 증강을 사용하여 TypeScript의 이점을 이용하고 코드베이스를 강화합니다.
TypeScript 구성에 자동 생성된 타입을 포함해야 합니다.
json5
1// tsconfig.json
2
3{
4 // 사용자 정의 구성
5 include: [
6 "src",
7 "types", // <- 자동 생성된 타입 포함
8 ],
9}Git 구성
Intlayer에 의해 생성된 파일을 무시하는 것이 좋습니다. 이렇게 하면 Git 리포지토리에 커밋하는 것에서 벗어날 수 있습니다.
이를 위해 .gitignore 파일에 다음 지침을 추가하세요:
gitignore
1# Intlayer에 의해 생성된 파일 무시
2.intlayer이 문서를 개선할 아이디어가 있으시면 GitHub에 풀 리퀘스트를 제출하여 자유롭게 기여해 주세요.
문서에 대한 GitHub 링크