@intlayer/docs 7.0.4-canary.0 → 7.0.4

package/blog/ko/intlayer_with_next-intl.md

@@ -1,392 +1,133 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer와 next-intl
-description: React 앱을 위해 next-intl와 Intlayer를 통합하다
-keywords:
-  - next-intl
-  - Intlayer
-  - 국제화
-  - 문서화
-  - Next.js
-  - JavaScript
-  - React
+updatedAt: 2025-10-29
+title: Intlayer를 사용하여 next-intl JSON 번역 자동화하는 방법
+description: Next.js 애플리케이션에서 향상된 국제화를 위해 Intlayer와 next-intl을 사용하여 JSON 번역을 자동화하세요.
 slugs:
   - blog
   - intlayer-with-next-intl
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: syncJSON 플러그인으로 변경
 ---
 
-# Next.js 국제화(i18n) with next-intl 및 Intlayer
+# Intlayer를 사용하여 next-intl JSON 번역 자동화하는 방법
 
-next-intl과 Intlayer는 Next.js 애플리케이션을 위해 설계된 오픈 소스 국제화(i18n) 프레임워크입니다. 이들은 소프트웨어 프로젝트에서 번역, 지역화 및 언어 전환 관리를 위해 널리 사용됩니다.
+## Intlayer란 무엇인가요?
 
-이들은 세 가지 주요 개념을 공유합니다:
+**Intlayer**는 기존 i18n 솔루션의 한계를 극복하기 위해 설계된 혁신적이고 오픈 소스인 국제화 라이브러리입니다. Next.js 애플리케이션에서 콘텐츠 관리를 위한 현대적인 접근 방식을 제공합니다.
 
-1. **콘텐츠 선언**: 애플리케이션의 번역 가능한 콘텐츠를 정의하는 방법입니다.
-   - Intlayer에서 `content declaration file`이라고 불리는 이 파일은 구조화된 데이터를 내보내는 JSON, JS 또는 TS 파일이 될 수 있습니다. 자세한 내용은 [Intlayer 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/concept/content)에서 확인하세요.
-   - next-intl에서는 일반적으로 JSON 파일에서 `messages` 또는 `locale messages`라고 불립니다. 자세한 내용은 [next-intl 문서](https://github.com/amannn/next-intl)에서 확인하세요.
+next-intl과의 구체적인 비교는 저희 [next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/next-i18next_vs_next-intl_vs_intlayer.md) 블로그 게시물을 참고하세요.
 
-2. **유틸리티**: 애플리케이션 내에서 콘텐츠 선언을 구축하고 해석하기 위한 도구로, Intlayer의 `useIntlayer()` 또는 `useLocale()`, next-intl의 `useTranslations()` 등이 있습니다.
+## 왜 Intlayer와 next-intl을 함께 사용해야 하나요?
 
-3. **플러그인 및 미들웨어**: URL 리디렉션 관리, 번들 최적화 등을 위한 기능 - 예를 들어, Intlayer의 `intlayerMiddleware` 또는 next-intl의 [`createMiddleware`](https://github.com/amannn/next-intl) 등이 있습니다.
+Intlayer는 훌륭한 독립형 i18n 솔루션을 제공하지만(자세한 내용은 저희 [Next.js 통합 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_16.md)를 참조), 다음과 같은 여러 이유로 next-intl과 함께 사용하고자 할 수 있습니다:
 
-## Intlayer vs. next-intl: 주요 차이점
+1. **기존 코드베이스**: 이미 구축된 next-intl 구현이 있으며 Intlayer의 향상된 개발자 경험으로 점진적으로 이전하고자 할 때.
+2. **레거시 요구사항**: 프로젝트가 기존 next-intl 플러그인이나 워크플로우와의 호환성을 필요로 할 때.
+3. **팀 친숙도**: 팀이 next-intl에 익숙하지만 더 나은 콘텐츠 관리를 원할 때.
 
-Intlayer가 next.js의 다른 i18n 라이브러리(예: next-intl)와 어떻게 비교되는지에 대한 더 깊은 분석을 위해서는 [next-i18next vs. next-intl vs. Intlayer 블로그 포스트](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/i18next_vs_next-intl_vs_intlayer.md)를 확인하세요.
+**이를 위해 Intlayer는 next-intl의 어댑터로 구현되어 CLI 또는 CI/CD 파이프라인에서 JSON 번역 자동화, 번역 테스트 등 다양한 작업을 지원할 수 있습니다.**
 
-## Intlayer로 next-intl 메시지 생성 방법
+이 가이드는 next-intl과의 호환성을 유지하면서 Intlayer의 우수한 콘텐츠 선언 시스템을 활용하는 방법을 보여줍니다.
 
-### Intlayer를 next-intl과 함께 사용해야 하는 이유는 무엇인가요?
+## 목차
 
-Intlayer 콘텐츠 선언 파일은 일반적으로 더 나은 개발자 경험을 제공합니다. 두 가지 주요 이점 때문에 더 유연하고 유지 관리가 용이합니다:
+<TOC/>
 
-1. **유연한 배치**: Intlayer 콘텐츠 선언 파일을 애플리케이션의 파일 트리 어디에나 배치할 수 있습니다. 이를 통해 사용되지 않거나 남아 있는 메시지 파일 없이 구성 요소의 이름을 바꾸거나 삭제할 수 있습니다.
+## next-intl과 함께 Intlayer 설정 단계별 가이드
 
-   예시 파일 구조:
+### 1단계: 의존성 설치
 
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # 콘텐츠 선언 파일
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # 콘텐츠 선언 파일
-               └── index.mjx
-   ```
-
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # 콘텐츠 선언 파일
-               └── index.cjx
-   ```
-
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # 콘텐츠 선언 파일
-               └── index.jsx
-   ```
-
-2. **중앙집중식 번역**: Intlayer는 모든 번역을 하나의 콘텐츠 선언에 저장하여 아무런 번역도 누락되지 않도록 합니다. TypeScript 프로젝트에서는 누락된 번역이 자동으로 타입 오류로 표시되어 개발자가 즉각적으로 피드백을 받을 수 있습니다.
-
-### 설치
-
-Intlayer와 next-intl을 함께 사용하려면 두 라이브러리를 모두 설치해야 합니다:
+필요한 패키지를 설치하세요:
 
 ```bash packageManager="npm"
-npm install intlayer next-intl
-```
-
-```bash packageManager="yarn"
-yarn add intlayer next-intl
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
 ```bash packageManager="pnpm"
-pnpm add intlayer next-intl
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-### Intlayer를 구성하여 next-intl 메시지 내보내기
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
+```
 
-> **참고:** Intlayer에서 next-intl용 메시지를 내보내면 구조에 약간의 차이가 발생할 수 있습니다. 가능하다면 Intlayer 전용 또는 next-intl 전용 플로우를 유지하여 통합을 간소화하세요. Intlayer에서 next-intl 메시지를 생성해야 하는 경우 아래 단계를 따르세요.
+**패키지 설명:**
 
-프로젝트의 루트에 있는 `intlayer.config.ts` 파일(또는 `.mjs` / `.cjs`)을 생성하거나 업데이트하세요:
+- **intlayer**: 국제화 관리, 콘텐츠 선언 및 빌드를 위한 핵심 라이브러리
+- **@intlayer/sync-json-plugin**: Intlayer 콘텐츠 선언을 next-intl 호환 JSON 형식으로 내보내는 플러그인
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
+### 2단계: JSON을 래핑하기 위한 Intlayer 플러그인 구현
 
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["next-intl"], // next-intl 출력을 사용
-    nextIntlMessagesDir: "./intl/messages", // next-intl 메시지를 저장할 위치
-  },
-};
+지원하는 로케일을 정의하기 위해 Intlayer 구성 파일을 만듭니다:
 
-export default config;
-```
+**next-intl용 JSON 사전도 내보내고 싶다면**, `syncJSON` 플러그인을 추가하세요:
 
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
+const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
   },
-  content: {
-    dictionaryOutput: ["react-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
+    }),
+  ],
 };
 
 export default config;
 ```
 
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["next-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
-
-module.exports = config;
-```
-
-### 콘텐츠 선언
+`syncJSON` 플러그인은 JSON을 자동으로 래핑합니다. 콘텐츠 구조를 변경하지 않고 JSON 파일을 읽고 씁니다.
 
-다음은 여러 형식의 콘텐츠 선언 파일 예시입니다. Intlayer는 이를 next-intl이 소비할 수 있는 메시지 파일로 컴파일합니다.
+만약 JSON과 intlayer 콘텐츠 선언 파일(`.content` 파일)을 공존시키고 싶다면, Intlayer는 다음과 같이 처리합니다:
 
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
-import { t, type Dictionary } from "intlayer";
+    1. JSON과 콘텐츠 선언 파일을 모두 불러와 intlayer 사전으로 변환합니다.
 
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-} satisfies Dictionary;
-
-export default content;
-```
+2. JSON과 콘텐츠 선언 파일 간에 충돌이 있는 경우, Intlayer는 모든 사전을 병합하는 과정을 진행합니다. 이는 플러그인의 우선순위와 콘텐츠 선언 파일의 우선순위에 따라 달라지며(모두 구성 가능) 처리됩니다.
 
-```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
-import { t } from "intlayer";
-
-/** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
+CLI를 사용하여 JSON을 번역하거나 CMS를 통해 변경 사항이 발생하면, Intlayer는 새로운 번역으로 JSON 파일을 업데이트합니다.
 
-export default content;
-```
+## Git 구성
 
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
+자동 생성된 Intlayer 파일은 무시하는 것이 권장됩니다:
 
-module.exports = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
+```plaintext fileName=".gitignore"
+# Intlayer에서 생성된 파일 무시
+.intlayer
 ```
 
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "my-component",
-  "content": {
-    "helloWorld": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Hello World",
-        "fr": "Bonjour le monde",
-        "es": "Hola Mundo"
-      }
-    }
-  }
-}
-```
+이 파일들은 빌드 과정 중에 다시 생성될 수 있으므로 버전 관리에 커밋할 필요가 없습니다.
 
-### next-intl 메시지 빌드
+### VS Code 확장 프로그램
 
-next-intl용 메시지 파일을 빌드하려면 다음을 실행하세요:
+개발자 경험 향상을 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치하세요:
 
-```bash packageManager="npm"
-npx intlayer dictionaries build
-```
+[VS Code 마켓플레이스에서 설치](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-```bash packageManager="yarn"
-yarn intlayer build
-```
+2. JSON과 콘텐츠 선언 파일 간에 충돌이 있는 경우, Intlayer는 모든 사전을 병합하여 처리합니다. 플러그인의 우선순위와 콘텐츠 선언 파일의 우선순위에 따라 달라집니다(모두 구성 가능합니다).
 
-```bash packageManager="pnpm"
-pnpm intlayer build
-```
+CLI를 사용하여 JSON 번역을 변경하거나 CMS를 사용하여 변경하면, Intlayer는 새로운 번역으로 JSON 파일을 업데이트합니다.
 
-이 명령은 `./intl/messages` 디렉토리에 리소스를 생성합니다(이는 `intlayer.config.*`에 구성되어 있습니다). 예상 출력은 다음과 같습니다:
-
-```bash
-.
-└── intl
-    └── messages
-       └── ko
-           └── my-content.json
-       └── fr
-           └── my-content.json
-       └── es
-           └── my-content.json
-```
+## Git 구성
 
-각 파일은 모든 Intlayer 콘텐츠 선언으로부터 컴파일된 메시지를 포함합니다. 최상위 키는 일반적으로 `content.key` 필드와 일치합니다.
-
-### 다음.js 앱에서 next-intl 사용하기
-
-> 더 자세한 내용은 공식 [next-intl 사용 문서](https://github.com/amannn/next-intl#readme)를 참조하세요.
-
-1. **미들웨어 생성 (선택 사항):**  
-   자동 언어 감지 또는 리디렉션을 관리하려면 next-intl의 [createMiddleware](https://github.com/amannn/next-intl#createMiddleware)를 사용하세요.
-
-   ```typescript fileName="middleware.ts"
-   import createMiddleware from "next-intl/middleware";
-   import { NextResponse } from "next/server";
-
-   export default createMiddleware({
-     locales: ["en", "fr", "es"],
-     defaultLocale: "en",
-   });
-
-   export const config = {
-     matcher: ["/((?!api|_next|.*\\..*).*)"],
-   };
-   ```
-
-2. **메시지를 로드하기 위한 `layout.tsx` 또는 `_app.tsx` 생성:**  
-   App Router(Next.js 13+)를 사용하는 경우 레이아웃을 생성하세요:
-
-   ```typescript fileName="app/[locale]/layout.tsx"
-   import { NextIntlClientProvider } from 'next-intl';
-   import { notFound } from 'next/navigation';
-   import React, { ReactNode } from 'react';
-
-
-   export default async function RootLayout({
-     children,
-     params
-   }: {
-     children: ReactNode;
-     params: { locale: string };
-   }) {
-     let messages;
-     try {
-       messages = (await import(`../../intl/messages/${params.locale}.json`)).default;
-     } catch (error) {
-       notFound();
-     }
-
-     return (
-       <html lang={params.locale}>
-         <body>
-           <NextIntlClientProvider locale={params.locale} messages={messages}>
-             {children}
-           </NextIntlClientProvider>
-         </body>
-       </html>
-     );
-   }
-   ```
-
-   페이지 라우터(Next.js 12 이하)를 사용하는 경우 `_app.tsx`에서 메시지를 로드하세요:
-
-   ```typescript fileName="pages/_app.tsx"
-   import type { AppProps } from 'next/app';
-   import { NextIntlProvider } from 'next-intl';
-
-   function MyApp({ Component, pageProps }: AppProps) {
-     return (
-       <NextIntlProvider locale={pageProps.locale} messages={pageProps.messages}>
-         <Component {...pageProps} />
-       </NextIntlProvider>
-     );
-   }
-
-   export default MyApp;
-   ```
-
-3. **서버 측에서 메시지 가져오기 (페이지 라우터 예시):**
-
-   ```typescript fileName="pages/index.tsx"
-   import { GetServerSideProps } from "next";
-   import HomePage from "../components/HomePage";
-
-   export default HomePage;
-
-   export const getServerSideProps: GetServerSideProps = async ({ locale }) => {
-     const messages = (await import(`../intl/messages/${locale}.json`)).default;
-
-     return {
-       props: {
-         locale,
-         messages,
-       },
-     };
-   };
-   ```
-
-### Next.js 구성 요소에서 콘텐츠 사용하기
-
-메시지가 next-intl에 로드된 후, `useTranslations()` 후크를 통해 구성 요소에서 사용할 수 있습니다:
-
-```typescript fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
-import type { FC } from "react";
-import { useTranslations } from 'next-intl';
-
-const MyComponent: FC = () => {
-  const t = useTranslations('my-component');
-  // 'my-component'는 Intlayer의 콘텐츠 키에 해당합니다.
-
-  return (
-    <div>
-      <h1>{t('helloWorld')}</h1>
-    </div>
-  );
-};
+자동 생성된 Intlayer 파일을 무시하는 것이 권장됩니다:
 
-export default MyComponent;
+```plaintext fileName=".gitignore"
+# Intlayer에서 생성된 파일 무시
+.intlayer
 ```
 
-```jsx fileName="src/components/MyComponent/index.jsx" codeFormat="esm"
-import { useTranslations } from "next-intl";
+이 파일들은 빌드 과정에서 다시 생성될 수 있으므로 버전 관리에 커밋할 필요가 없습니다.
 
-export default function MyComponent() {
-  const t = useTranslations("my-component");
+### VS Code 확장 프로그램
 
-  return (
-    <div>
-      <h1>{t("helloWorld")}</h1>
-    </div>
-  );
-}
-```
+개발자 경험 향상을 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치하세요:
 
-**그게 전부입니다!** Intlayer 콘텐츠 선언 파일을 업데이트하거나 새로 추가할 때마다 `intlayer build` 명령을 다시 실행하여 next-intl JSON 메시지를 재생성하세요. next-intl은 업데이트된 콘텐츠를 자동으로 가져옵니다.
+[VS Code 마켓플레이스에서 설치하기](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)