@intlayer/docs 7.0.4-canary.0 → 7.0.5

package/blog/ko/intlayer_with_react-i18next.md

@@ -1,346 +1,124 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer와 react-i18next
-description: React 앱을 위해 react-i18next와 Intlayer를 비교하다
+updatedAt: 2025-10-29
+title: Intlayer를 사용하여 react-i18next JSON 번역 자동화하는 방법
+description: React 애플리케이션에서 향상된 국제화를 위해 Intlayer와 react-i18next를 사용하여 JSON 번역을 자동화하세요.
 keywords:
   - react-i18next
   - i18next
   - Intlayer
   - 국제화
-  - 문서화
-  - Next.js
-  - JavaScript
+  - i18n
+  - 블로그
   - React
+  - JavaScript
+  - TypeScript
+  - 콘텐츠 관리
 slugs:
   - blog
   - intlayer-with-react-i18next
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: syncJSON 플러그인으로 변경
 ---
 
-# React 국제화 (i18n) react-i18next 및 Intlayer와 함께
-
-## 개요
-
-- **Intlayer**는 **구성 요소 수준**의 콘텐츠 선언 파일을 통해 번역 관리를 도와줍니다.
-- **react-i18next**는 **i18next**에 대한 인기 있는 React 통합으로, `useTranslation`과 같은 후크를 제공하여 구성 요소에서 지역화된 문자열을 가져옵니다.
-
-결합하면, Intlayer는 **i18next 호환 JSON** 사전을 **내보내기**하므로 react-i18next가 런타임에서 이를 **소비**할 수 있습니다.
-
-## 왜 react-i18next와 함께 Intlayer를 사용해야 할까요?
-
-**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. **중앙 집중식 번역**  
-   단일 콘텐츠 선언 파일이 구성 요소에 필요한 모든 번역을 수집하여 누락된 번역을 쉽게 식별할 수 있게 합니다.  
-   TypeScript를 사용하면 번역이 누락될 경우 컴파일 타임 오류도 발생합니다.
-
-## 설치
-
-Create React App 프로젝트에서 다음 종속성을 설치하세요:
-
-```bash
-# npm으로
-npm install intlayer react-i18next i18next i18next-resources-to-backend
-```
-
-```bash
-# yarn으로
-yarn add intlayer react-i18next i18next i18next-resources-to-backend
-```
-
-```bash
-# pnpm으로
-pnpm add intlayer react-i18next i18next i18next-resources-to-backend
-```
+# Intlayer를 사용하여 react-i18next JSON 번역 자동화하는 방법
 
-### 이 패키지들은 무엇인가요?
+## Intlayer란 무엇인가요?
 
-- **intlayer** – i18n 구성, 콘텐츠 선언 관리 및 사전 출력을 구축하기 위한 CLI 및 핵심 라이브러리입니다.
-- **react-intlayer** – 사전 구축 자동화를 위한 스크립트를 제공하는 Intlayer의 React 전용 통합입니다.
-- **react-i18next** – i18next를 위한 React 전용 통합 라이브러리로, `useTranslation` 후크를 포함합니다.
-- **i18next** – 번역 처리를 위한 기본 프레임워크입니다.
-- **i18next-resources-to-backend** – JSON 리소스를 동적으로 가져오는 i18next 백엔드입니다.
+**Intlayer**는 전통적인 i18n 솔루션의 한계를 극복하기 위해 설계된 혁신적이고 오픈 소스인 국제화 라이브러리입니다. React 애플리케이션에서 콘텐츠 관리를 위한 현대적인 접근 방식을 제공합니다.
 
-## Intlayer를 구성하여 i18next 사전 내보내기
-
-프로젝트의 최상위에 `intlayer.config.ts`를 생성 (또는 업데이트) 하세요:
-
-```typescript title="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    // 원하는 만큼의 로케일 추가
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    // Intlayer에 i18next 호환 JSON 생성을 지시
-    dictionaryOutput: ["i18next"],
+react-i18next와의 구체적인 비교는 저희 [react-i18next vs. react-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/react-i18next_vs_react-intl_vs_intlayer.md) 블로그 게시물을 참고하세요.
 
-    // 생성된 리소스의 출력 디렉토리 선택
-    // 이 폴더는 아직 존재하지 않는 경우 생성됩니다.
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
+## 왜 Intlayer를 react-i18next와 결합해야 하나요?
 
-export default config;
-```
+Intlayer는 훌륭한 독립형 i18n 솔루션을 제공하지만(자세한 내용은 저희 [React 통합 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_vite+react.md)를 참조), 다음과 같은 여러 이유로 react-i18next와 결합하여 사용하고자 할 수 있습니다:
 
-> **참고**: TypeScript를 사용하지 않는 경우, 이 구성 파일을 `.cjs`, `.mjs` 또는 `.js`로 생성할 수 있습니다 (자세한 내용은 [Intlayer 문서](https://intlayer.org/en/doc/concept/configuration)를 참조하세요).
+1. **기존 코드베이스**: 이미 구축된 react-i18next 구현이 있으며 Intlayer의 향상된 개발자 경험으로 점진적으로 이전하고자 할 때.
+2. **레거시 요구사항**: 프로젝트가 기존 react-i18next 플러그인 또는 워크플로우와의 호환성을 필요로 할 때.
+3. **팀 친숙도**: 팀이 react-i18next에 익숙하지만 더 나은 콘텐츠 관리를 원할 때.
 
-## i18next 리소스 구축
+**이를 위해 Intlayer는 react-i18next의 어댑터로 구현되어 CLI 또는 CI/CD 파이프라인에서 JSON 번역 자동화, 번역 테스트 등 다양한 작업을 지원할 수 있습니다.**
 
-콘텐츠 선언이 준비된 후 (다음 섹션), **Intlayer 빌드 명령**을 실행하세요:
+이 가이드는 react-i18next와의 호환성을 유지하면서 Intlayer의 우수한 콘텐츠 선언 시스템을 활용하는 방법을 보여줍니다.
 
-```bash
-# npm으로
-npx run intlayer build
-```
+## 목차
 
-```bash
-# yarn으로
-yarn intlayer build
-```
+<TOC/>
 
-```bash
-# pnpm으로
-pnpm intlayer build
-```
+## react-i18next와 함께 Intlayer 설정 단계별 가이드
 
-> 이렇게 하면 기본적으로 `./i18next/resources` 디렉토리에 i18next 리소스가 생성됩니다.
+### 1단계: 의존성 설치
 
-일반적인 출력 예시는 다음과 같습니다:
+필요한 패키지를 설치하세요:
 
-```bash
-.
-└── i18next
-    └── resources
-       ├── ko
-       │   └── my-content.json
-       ├── fr
-       │   └── my-content.json
-       └── es
-           └── my-content.json
+```bash packageManager="npm"
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-각 **Intlayer** 선언 키는 **i18next 네임스페이스**로 사용됩니다 (예: `my-content.json`).
-
-## react-i18next 구성에 사전을 가져오기
-
-런타임에서 이러한 리소스를 동적으로 로드하려면 [`i18next-resources-to-backend`](https://www.npmjs.com/package/i18next-resources-to-backend)를 사용하세요. 예를 들어, 프로젝트에 `i18n.ts` (또는 `.js`) 파일을 생성하세요:
-
-```typescript title="i18n.ts"
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next
-  // react-i18next 플러그인
-  .use(initReactI18next)
-  // 동적으로 리소스 로드
-  .use(
-    resourcesToBackend((language: string, namespace: string) => {
-      // 리소스 디렉토리에 대한 가져오기 경로 조정
-      return import(`../i18next/resources/${language}/${namespace}.json`);
-    })
-  )
-  // i18next 초기화
-  .init({
-    // 폴백 로케일
-    fallbackLng: "en",
-
-    // 여기에서 기타 i18next 구성 옵션을 추가할 수 있습니다. 참조:
-    // https://www.i18next.com/overview/configuration-options
-  });
-
-export default i18next;
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```javascript title="i18n.js"
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next
-  .use(initReactI18next)
-  .use(
-    resourcesToBackend(
-      (language, namespace) =>
-        import(`../i18next/resources/${language}/${namespace}.json`)
-    )
-  )
-  .init({
-    fallbackLng: "en",
-  });
-
-export default i18next;
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-그런 다음 **루트** 또는 **인덱스** 파일 (예: `src/index.tsx`)에서 `App`을 렌더링하기 전에 이 `i18n` 설정을 가져옵니다:
+**패키지 설명:**
 
-```typescript
-import React from "react";
-import ReactDOM from "react-dom/client";
-// 아무것도 하기 전에 i18n 초기화
-import "./i18n";
-import App from "./App";
+- **intlayer**: 국제화 관리, 콘텐츠 선언 및 빌드를 위한 핵심 라이브러리
+- **@intlayer/sync-json-plugin**: Intlayer 콘텐츠 선언을 react-i18next 호환 JSON 형식으로 내보내는 플러그인
 
-ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
-```
+### 2단계: JSON을 감싸는 Intlayer 플러그인 구현
 
-## 콘텐츠 선언 작성 및 관리
+지원하는 로케일을 정의하는 Intlayer 구성 파일을 만드세요:
 
-Intlayer는 `./src` 아래에 위치한 "콘텐츠 선언 파일"에서 번역을 추출합니다 (기본값).  
-여기 TypeScript의 최소 예시가 있습니다:
+**react-i18next용 JSON 사전도 내보내고 싶다면**, `syncJSON` 플러그인을 추가하세요:
 
-```typescript title="src/components/MyComponent/MyComponent.content.ts"
-import { t, type Dictionary } from "intlayer";
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-const content = {
-  // "key"는 당신의 i18next 네임스페이스가 됩니다 (예: "my-component")
-  key: "my-component",
-  content: {
-    // 각 "t" 호출은 별개의 번역 노드입니다
-    heading: t({
-      ko: "안녕하세요 세계",
-      fr: "Bonjour le monde",
-      es: "Hola Mundo",
-    }),
-    description: t({
-      ko: "내 i18n 설명 텍스트...",
-      fr: "Ma description en i18n...",
-      es: "Mi descripción en i18n...",
-    }),
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
   },
-} satisfies Dictionary;
-
-export default content;
-```
-
-JSON, `.cjs` 또는 `.mjs`를 선호하는 경우 [Intlayer 문서](https://intlayer.org/en/doc/concept/content)를 참조하세요.
-
-> 기본적으로 유효한 콘텐츠 선언은 파일 확장자 패턴과 일치합니다:
-
-> `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`
-
-## React 구성 요소에서 번역 사용하기
-
-Intlayer 리소스를 **구축**하고 react-i18next를 구성한 후, **react-i18next**에서 `useTranslation` 후크를 직접 사용할 수 있습니다.  
-예를 들면:
-
-```tsx title="src/components/MyComponent/MyComponent.tsx"
-import type { FC } from "react";
-import { useTranslation } from "react-i18next";
-
-/**
- * i18next "네임스페이스"는 "MyComponent.content.ts"의 Intlayer `key`입니다
- * 따라서 "my-component"를 useTranslation()에 전달하겠습니다.
- */
-const MyComponent: FC = () => {
-  const { t } = useTranslation("my-component");
-
-  return (
-    <div>
-      <h1>{t("heading")}</h1>
-      <p>{t("description")}</p>
-    </div>
-  );
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
+    }),
+  ],
 };
 
-export default MyComponent;
+export default config;
 ```
 
-> `t` 함수는 생성된 JSON 내부의 **키**를 참조한다는 점에 유의하세요. Intlayer 콘텐츠 항목 이름이 `heading`인 경우, `t("heading")`을 사용합니다.
+`syncJSON` 플러그인은 JSON을 자동으로 래핑합니다. 콘텐츠 구조를 변경하지 않고 JSON 파일을 읽고 씁니다.
 
-## 선택 사항: Create React App 스크립트와 통합 (CRACO)
+만약 JSON과 intlayer 콘텐츠 선언 파일(`.content` 파일)을 공존시키고 싶다면, Intlayer는 다음과 같이 처리합니다:
 
-**react-intlayer**는 사용자 정의 빌드 및 개발 서버 구성을 위한 CRACO 기반 접근 방식을 제공합니다. Intlayer의 빌드 단계를 원활하게 통합하고 싶다면:
+1. JSON과 콘텐츠 선언 파일을 모두 로드하여 Intlayer 사전으로 변환합니다.
+2. JSON과 콘텐츠 선언 파일 간에 충돌이 있을 경우, Intlayer는 모든 사전을 병합합니다. 이 과정은 플러그인의 우선순위와 콘텐츠 선언 파일의 우선순위에 따라 결정됩니다(모두 구성 가능).
 
-1. **react-intlayer 설치** (아직 설치하지 않았다면):
-   ```bash
-   npm install react-intlayer --save-dev
-   ```
-2. **`package.json` 스크립트를 조정**하여 `react-intlayer` 스크립트를 사용하세요:
+CLI를 사용하여 JSON을 번역하거나 CMS를 통해 변경 사항이 발생하면, Intlayer는 새로운 번역으로 JSON 파일을 업데이트합니다.
 
-   ```jsonc
-   "scripts": {
-     "start": "react-intlayer start",
-     "build": "react-intlayer build",
-     "transpile": "intlayer build"
-   }
-   ```
+`syncJSON` 플러그인에 대한 자세한 내용은 [syncJSON 플러그인 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/plugins/sync-json.md)를 참조하세요.
 
-   > `react-intlayer` 스크립트는 [CRACO](https://craco.js.org/)를 기반으로 합니다. 또한 intlayer craco 플러그인을 기반으로 한 자신의 설정을 구현할 수 있습니다. [여기에서 예시 확인](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
-
-이제 `npm run build`, `yarn build` 또는 `pnpm build`를 실행하면 Intlayer와 CRA 빌드를 모두 트리거할 수 있습니다.
-
-## TypeScript 구성
+## Git 구성
 
-**Intlayer**는 콘텐츠에 대한 **자동 생성된 타입 정의**를 제공합니다. TypeScript가 이를 인식하도록 하려면, **`types`** (또는 다르게 구성한 경우 `types`)를 `tsconfig.json` **include** 배열에 추가하세요:
+자동 생성된 Intlayer 파일은 무시하는 것이 권장됩니다:
 
-```json5 title="tsconfig.json"
-{
-  "compilerOptions": {
-    // ...
-  },
-  "include": ["src", "types"],
-}
+```plaintext fileName=".gitignore"
+# Intlayer에서 생성된 파일 무시하기
+.intlayer
 ```
 
-> 이렇게 하면 TypeScript가 번역의 형식을 추론하여 더 나은 자동 완성과 오류 감지를 제공합니다.
-
-## Git 구성
+이 파일들은 빌드 과정에서 다시 생성될 수 있으므로 버전 관리에 커밋할 필요가 없습니다.
 
-자동 생성된 파일과 폴더를 Intlayer에서 **무시하는 것이 좋습니다**. 다음 줄을 `.gitignore`에 추가하세요:
+### VS Code 확장 프로그램
 
-```plaintext
-# Intlayer에 의해 생성된 파일 무시
-.intlayer
-i18next
-```
+개발자 경험을 향상시키기 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치하세요:
 
-이러한 리소스나 `.intlayer` 내부 빌드 아티팩트를 커밋하지 않는 것이 일반적입니다, 왜냐하면 이들은 매 빌드마다 재생성될 수 있기 때문입니다.
+[VS Code 마켓플레이스에서 설치하기](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)