Intlayer

--- createdAt: 2025-08-23 updatedAt: 2025-10-29 title: Intlayer와 next-i18next description: 포괄적인 Next.js 국제화 솔루션을 위한 Intlayer와 next-i18next 통합 keywords: - i18next - next-i18next - Intlayer - 국제화 - 블로그 - Next.js - 자바스크립트 - 리액트 slugs: - blog - intlayer-with-next-i18next youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg history: - version: 7.0.6 date: 2025-11-01 changes: loadJSON 플러그인 추가 - version: 7.0.0 date: 2025-10-29 changes: syncJSON 플러그인으로 변경 및 전면 개편 --- # next-i18next와 Intlayer를 활용한 Next.js 국제화(i18n) <iframe title="Intlayer를 사용하여 next-i18next JSON 번역 자동화하는 방법" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/> ## 목차 <TOC/> ## next-i18next란 무엇인가? **next-i18next**는 Next.js 애플리케이션을 위한 가장 인기 있는 국제화(i18n) 프레임워크 중 하나입니다. 강력한 **i18next** 생태계 위에 구축되어, Next.js 프로젝트에서 번역, 현지화, 언어 전환을 관리하는 포괄적인 솔루션을 제공합니다. 하지만 next-i18next에는 몇 가지 어려움이 있습니다: - **복잡한 설정**: next-i18next를 설정하려면 여러 구성 파일과 서버 측 및 클라이언트 측 i18n 인스턴스의 신중한 설정이 필요합니다. - **분산된 번역 파일**: 번역 파일이 일반적으로 컴포넌트와 별도의 디렉토리에 저장되어 일관성을 유지하기 어렵습니다. - **수동 네임스페이스 관리**: 개발자가 네임스페이스를 수동으로 관리하고 번역 리소스가 제대로 로드되도록 해야 합니다. - **제한된 타입 안전성**: TypeScript 지원은 추가 구성이 필요하며 번역에 대한 자동 타입 생성을 제공하지 않습니다. ## Intlayer란 무엇인가요? **Intlayer**는 전통적인 i18n 솔루션의 단점을 해결하기 위해 설계된 혁신적이고 오픈 소스인 국제화 라이브러리입니다. Next.js 애플리케이션에서 콘텐츠 관리를 위한 현대적인 접근 방식을 제공합니다. [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) 블로그 게시물에서 next-intl과의 구체적인 비교를 확인하세요. ## 왜 Intlayer를 next-i18next와 결합해야 하나요? Intlayer가 훌륭한 독립형 i18n 솔루션을 제공하지만(자세한 내용은 [Next.js 통합 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_16.md) 참조), 다음과 같은 여러 이유로 next-i18next와 결합하여 사용할 수 있습니다: 1. **기존 코드베이스**: 이미 구축된 next-i18next 구현이 있으며 Intlayer의 향상된 개발자 경험으로 점진적으로 마이그레이션하려는 경우. 2. **레거시 요구사항**: 프로젝트가 기존 i18next 플러그인 또는 워크플로우와의 호환성을 필요로 하는 경우. 3. **팀 친숙도**: 팀이 next-i18next에 익숙하지만 더 나은 콘텐츠 관리를 원할 경우. **이를 위해, Intlayer는 next-i18next의 어댑터로 구현되어 CLI 또는 CI/CD 파이프라인에서 JSON 번역 자동화, 번역 테스트 등 다양한 작업을 지원할 수 있습니다.** 이 가이드는 next-i18next와의 호환성을 유지하면서 Intlayer의 우수한 콘텐츠 선언 시스템을 활용하는 방법을 보여줍니다. --- ## next-i18next와 함께 Intlayer 설정 단계별 가이드 ### 1단계: 의존성 설치 선호하는 패키지 관리자를 사용하여 필요한 패키지를 설치하세요: ```bash packageManager="npm" npm install intlayer @intlayer/sync-json-plugin ``` ```bash packageManager="pnpm" pnpm add intlayer @intlayer/sync-json-plugin ``` ```bash packageManager="yarn" yarn add intlayer @intlayer/sync-json-plugin ``` ```bash packageManager="bun" bun add intlayer @intlayer/sync-json-plugin ``` **패키지 설명:** - **intlayer**: 콘텐츠 선언 및 관리를 위한 핵심 라이브러리 - **@intlayer/sync-json-plugin**: Intlayer 콘텐츠 선언을 i18next JSON 형식과 동기화하는 플러그인 ### 2단계: JSON을 래핑하기 위한 Intlayer 플러그인 구현 지원하는 로케일을 정의하기 위해 Intlayer 구성 파일을 만듭니다: **i18next용 JSON 사전도 내보내고 싶다면**, `syncJSON` 플러그인을 추가하세요: ```typescript fileName="intlayer.config.ts" import { Locales, type IntlayerConfig } from "intlayer"; import { syncJSON } from "@intlayer/sync-json-plugin"; const config: IntlayerConfig = { internationalization: { locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], defaultLocale: Locales.ENGLISH, }, plugins: [ syncJSON({ format: "i18next", source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`, }), ], }; export default config; ``` `syncJSON` 플러그인은 JSON을 자동으로 래핑합니다. 콘텐츠 구조를 변경하지 않고 JSON 파일을 읽고 씁니다. 만약 JSON과 intlayer 콘텐츠 선언 파일(`.content` 파일)을 공존시키고 싶다면, Intlayer는 다음과 같이 처리합니다: 1. JSON과 콘텐츠 선언 파일을 모두 로드하여 intlayer 사전으로 변환합니다. 2. JSON과 콘텐츠 선언 파일 간에 충돌이 있을 경우, Intlayer는 모든 사전을 병합합니다. 이 과정은 플러그인의 우선순위와 콘텐츠 선언 파일의 우선순위에 따라 달라집니다(모두 구성 가능합니다). CLI를 사용하여 JSON을 번역하거나 CMS를 사용하여 변경 사항이 발생하면, Intlayer는 새로운 번역으로 JSON 파일을 업데이트합니다. `syncJSON` 플러그인에 대한 자세한 내용은 [syncJSON 플러그인 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/plugins/sync-json.md)를 참조하세요. --- ### (선택 사항) 3단계: 컴포넌트별 JSON 번역 구현 기본적으로 Intlayer는 JSON 파일과 콘텐츠 선언 파일을 모두 로드, 병합 및 동기화합니다. 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요. 하지만 원한다면 Intlayer 플러그인을 사용하여 코드베이스 어디에서나 지역화된 JSON을 컴포넌트별로 관리할 수도 있습니다. 이를 위해 `loadJSON` 플러그인을 사용할 수 있습니다. ```ts fileName="intlayer.config.ts" import { Locales, type IntlayerConfig } from "intlayer"; import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin"; const config: IntlayerConfig = { internationalization: { locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], defaultLocale: Locales.ENGLISH, }, // 현재 JSON 파일을 Intlayer 사전과 동기화 상태로 유지합니다 plugins: [ /** * src 내에서 {key}.i18n.json 패턴과 일치하는 모든 JSON 파일을 로드합니다 */ loadJSON({ source: ({ key }) => `./src/**/${key}.i18n.json`, locale: Locales.ENGLISH, priority: 1, // 이 JSON 파일들이 `./public/locales/en/${key}.json` 파일보다 우선권을 갖도록 보장합니다 }), /** * 로케일 디렉토리 내 JSON 파일에 출력 및 번역을 다시 작성하고 로드합니다. */ syncJSON({ format: "i18next", source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`, priority: 0, }), ], }; export default config; ``` 이 설정은 `src` 디렉토리 내에서 `{key}.i18n.json` 패턴과 일치하는 모든 JSON 파일을 로드하여 Intlayer 사전으로 불러옵니다. --- ## Git 구성 생성된 파일을 버전 관리에서 제외하세요: ```plaintext fileName=".gitignore" # Intlayer에서 생성된 파일 무시 .intlayer ``` 이 파일들은 빌드 과정에서 자동으로 다시 생성되므로 저장소에 커밋할 필요가 없습니다. ### VS Code 확장 프로그램 개발자 경험 향상을 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치하세요: [VS Code 마켓플레이스에서 설치하기](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension) 개발자 경험을 향상시키기 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치하세요: [VS Code 마켓플레이스에서 설치하기](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)