Intlayer

--- createdAt: 2025-01-02 updatedAt: 2025-06-29 title: react-i18next vs react-intl vs Intlayer description: React 앱의 국제화(i18n)를 위해 react-i18next를 next-intl 및 Intlayer와 통합하기 keywords: - next-intl - react-i18next - Intlayer - 국제화 - 블로그 - Next.js - 자바스크립트 - 리액트 slugs: - blog - react-i18next-vs-react-intl-vs-intlayer --- # react-Intl VS react-i18next VS intlayer | React 국제화 (i18n) 이 가이드는 **React**를 위한 세 가지 검증된 i18n 옵션인 **react-intl** (FormatJS), **react-i18next** (i18next), 그리고 **Intlayer**를 비교합니다. 우리는 **순수 React** 애플리케이션(예: Vite, CRA, SPA)에 중점을 둡니다. Next.js를 사용 중이라면, 전용 Next.js 비교를 참고하세요. 우리가 평가하는 항목은 다음과 같습니다: - 아키텍처 및 콘텐츠 구성 - TypeScript 및 안정성 - 누락된 번역 처리 - 풍부한 콘텐츠 및 포맷팅 기능 - 성능 및 로딩 동작 - 개발자 경험(DX), 도구 및 유지보수 - SEO/라우팅(프레임워크 의존) > **요약**: 세 가지 모두 React 앱을 현지화할 수 있습니다. 만약 **컴포넌트 범위 콘텐츠**, **엄격한 TypeScript 타입**, **빌드 시 누락 키 검사**, **트리 쉐이킹된 사전**, 그리고 내장된 편집 도구(비주얼 에디터/CMS + 선택적 AI 번역)를 원한다면, **Intlayer**가 모듈형 React 코드베이스에 가장 완벽한 선택입니다. --- ## 상위 수준 포지셔닝 - **react-intl** - ICU 우선, 표준에 맞는 포맷팅(날짜/숫자/복수형)과 성숙한 API를 제공. 카탈로그는 일반적으로 중앙 집중식이며, 키 안전성과 빌드 시 검증은 주로 사용자가 책임집니다. - **react-i18next** - 매우 인기 있고 유연함; 네임스페이스, 탐지기, 다양한 플러그인(ICU, 백엔드 등)을 지원. 강력하지만 프로젝트가 커질수록 설정이 복잡해질 수 있습니다. - **Intlayer** - React용 컴포넌트 중심 콘텐츠 모델, **엄격한 TS 타입 지정**, **빌드 시 검사**, **트리 쉐이킹**, 그리고 **비주얼 에디터/CMS** 및 **AI 지원 번역**을 포함. React Router, Vite, CRA 등과 호환됩니다. --- ## 기능 매트릭스 (React 중심) | 기능 | `react-intlayer` (Intlayer) | `react-i18next` (i18next) | `react-intl` (FormatJS) | | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | **컴포넌트 근처 번역** | ✅ 예, 각 컴포넌트와 내용이 함께 위치 | ❌ 아니요 | ❌ 아니요 | | **TypeScript 통합** | ✅ 고급, 자동 생성된 엄격한 타입 | ⚠️ 기본; 안전성을 위한 추가 설정 필요 | ✅ 좋음, 하지만 덜 엄격함 | | **누락된 번역 감지** | ✅ TypeScript 오류 하이라이트 및 빌드 시 오류/경고 | ⚠️ 대부분 런타임 시 폴백 문자열 | ⚠️ 폴백 문자열 | | **리치 콘텐츠 (JSX/Markdown/컴포넌트)** | ✅ 직접 지원 | ⚠️ 제한적 / 인터폴레이션만 | ⚠️ ICU 구문, 실제 JSX 아님 | | **AI 기반 번역** | ✅ 예, 여러 AI 제공자를 지원합니다. 자체 API 키를 사용하여 이용 가능하며, 애플리케이션과 콘텐츠 범위의 컨텍스트를 고려합니다. | ❌ 아니요 | ❌ 아니요 | | **비주얼 에디터** | ✅ 예, 로컬 비주얼 에디터 + 선택적 CMS 제공; 코드베이스 콘텐츠 외부화 가능; 임베드 가능 | ❌ 아니요 / 외부 현지화 플랫폼을 통해 이용 가능 | ❌ 아니요 / 외부 현지화 플랫폼을 통해 이용 가능 | | **로컬라이즈된 라우팅** | ✅ 예, 기본적으로 로컬라이즈된 경로를 지원함 (Next.js 및 Vite와 함께 작동) | ⚠️ 내장 기능 없음, 플러그인(예: `next-i18next`) 또는 커스텀 라우터 설정 필요 | ❌ 없음, 메시지 포맷팅만 지원하며 라우팅은 수동으로 처리해야 함 | | **동적 라우트 생성** | ✅ 예 | ⚠️ 플러그인/에코시스템 또는 수동 설정 필요 | ❌ 제공되지 않음 | | **복수형 처리** | ✅ 열거형 기반 패턴 | ✅ 구성 가능 (i18next-icu 같은 플러그인 사용) | ✅ (ICU) | | **포맷팅 (날짜, 숫자, 통화)** | ✅ 최적화된 포맷터 (내부적으로 Intl 사용) | ⚠️ 플러그인 또는 커스텀 Intl 사용 필요 | ✅ ICU 포맷터 | | **콘텐츠 형식** | ✅ .tsx, .ts, .js, .json, .md, .txt, (.yaml 작업 중) | ⚠️ .json | ✅ .json, .js | | **ICU 지원** | ⚠️ 작업 중 | ⚠️ 플러그인(i18next-icu)을 통해 | ✅ 예 | | **SEO 도우미 (hreflang, 사이트맵)** | ✅ 내장 도구: 사이트맵, robots.txt, 메타데이터 도우미 | ⚠️ 커뮤니티 플러그인/수동 | ❌ 핵심 기능 아님 | | **에코시스템 / 커뮤니티** | ⚠️ 작지만 빠르게 성장하고 반응성이 좋음 | ✅ 가장 크고 성숙함 | ✅ 큼 | | **서버 사이드 렌더링 및 서버 컴포넌트** | ✅ 예, SSR 및 React 서버 컴포넌트에 최적화됨 | ⚠️ 페이지 단위로 지원되나 자식 서버 컴포넌트에 t-함수를 컴포넌트 트리에 전달해야 함 | ❌ 지원하지 않음, 자식 서버 컴포넌트에 t-함수를 컴포넌트 트리에 전달해야 함 | | **트리 쉐이킹 (사용된 콘텐츠만 로드)** | ✅ 예, Babel/SWC 플러그인을 통한 빌드 시 컴포넌트별 적용 | ⚠️ 보통 전체를 로드함 (네임스페이스/코드 분할로 개선 가능) | ⚠️ 보통 전체를 로드함 | | **지연 로딩 (Lazy loading)** | ✅ 예, 로케일별 / 사전별 | ✅ 예 (예: 백엔드/네임스페이스 요청 시) | ✅ 예 (로케일 번들 분할) | | **사용하지 않는 콘텐츠 정리 (Purge unused content)** | ✅ 예, 빌드 시 사전별 | ❌ 아니요, 수동 네임스페이스 분할을 통해서만 가능 | ❌ 아니요, 선언된 모든 메시지가 번들에 포함됨 | | **대규모 프로젝트 관리** | ✅ 모듈화를 장려하며 디자인 시스템에 적합 | ⚠️ 체계적인 파일 관리 필요 | ⚠️ 중앙 카탈로그가 커질 수 있음 | --- ## 심층 비교 ### 1) 아키텍처 및 확장성 - **react-intl / react-i18next**: 대부분의 설정은 언어별로 **중앙 집중식 로케일 폴더**를 유지하며, 때로는 **네임스페이스**(i18next)로 분리됩니다. 초기에는 잘 작동하지만 앱이 커지면서 공유 영역이 됩니다. - **Intlayer**: UI와 함께 **컴포넌트별(또는 기능별) 사전**을 **동일 위치에 배치**하는 방식을 권장합니다. 이는 소유권을 명확히 하고, 컴포넌트 복제/이전을 용이하게 하며, 팀 간 키 변경을 줄여줍니다. 사용하지 않는 콘텐츠를 식별하고 제거하기도 쉽습니다. **중요한 이유:** 모듈화된 콘텐츠는 모듈화된 UI를 반영합니다. 대규모 React 코드베이스는 번역이 해당 컴포넌트와 함께 있을 때 더 깔끔하게 유지됩니다. --- ### 2) TypeScript 및 안정성 - **react-intl**: 견고한 타입 정의를 제공하지만, **자동 키 타입 지정은 없으며** 안전성 패턴을 직접 적용해야 합니다. - **react-i18next**: 훅에 대한 강력한 타입 정의를 제공하며, **엄격한 키 타입 지정은 보통 추가 설정이나 생성기가 필요**합니다. - **Intlayer**: 콘텐츠에서 **엄격한 타입을 자동 생성**합니다. IDE 자동완성과 **컴파일 타임 오류**가 런타임 전에 오타와 누락된 키를 잡아냅니다. **중요한 이유:** 실패를 **왼쪽으로 이동**(빌드/CI 단계로)시켜 프로덕션 문제를 줄이고 개발자 피드백 루프를 가속화합니다. --- ### 3) 누락된 번역 처리 - **react-intl / react-i18next**: 기본적으로 **런타임 폴백**(키 에코 또는 기본 로케일)으로 처리합니다. 린팅/플러그인을 추가할 수 있지만 빌드 시 보장은 없습니다. - **Intlayer**: 필수 로케일/키가 누락되면 **빌드 타임 감지**로 경고 또는 오류를 발생시킵니다. **중요한 이유:** CI가 누락된 문자열을 실패 처리하여 비영어 UI에 “미스터리 영어”가 유출되는 것을 방지합니다. --- ### 4) 풍부한 콘텐츠 및 포맷팅 - **react-intl**: 복수형, 선택형, 날짜/숫자, 메시지 구성에 대해 뛰어난 **ICU** 지원을 제공합니다. JSX를 사용할 수 있지만, 정신 모델은 메시지 중심으로 유지됩니다. - **react-i18next**: 유연한 보간법과 요소/컴포넌트를 포함할 수 있는 **`<Trans>`**를 지원하며, ICU는 플러그인을 통해 사용할 수 있습니다. - **Intlayer**: 콘텐츠 파일에 **리치 노드**(JSX/Markdown/컴포넌트)와 **메타데이터**를 포함할 수 있습니다. 포맷팅은 내부적으로 Intl을 사용하며, 복수형 패턴이 사용하기 편리합니다. **중요한 이유:** 복잡한 UI 텍스트(링크, 굵은 부분, 인라인 컴포넌트 등)는 라이브러리가 React 노드를 깔끔하게 수용할 때 더 쉽게 처리할 수 있습니다. --- ### 5) 성능 및 로딩 동작 - **react-intl / react-i18next**: 일반적으로 **카탈로그 분할**과 **지연 로딩**을 수동으로 관리합니다(네임스페이스/동적 임포트). 효과적이지만 규율이 필요합니다. - **Intlayer**: 사용하지 않는 사전을 **트리 쉐이킹**하고 **사전별/로케일별 지연 로딩**을 기본적으로 지원합니다. **중요한 이유:** 더 작은 번들과 사용하지 않는 문자열 감소는 시작 및 탐색 성능을 향상시킵니다. --- ### 6) 개발자 경험(DX), 도구 및 유지보수 - **react-intl / react-i18next**: 광범위한 커뮤니티 생태계; 편집 워크플로우를 위해 일반적으로 외부 현지화 플랫폼을 채택합니다. - **Intlayer**: **무료 비주얼 에디터**와 **선택적 CMS**(콘텐츠를 Git에 보관하거나 외부화 가능)를 제공합니다. 또한 콘텐츠 작성용 **VSCode 확장**과 자체 제공자 키를 사용하는 **AI 지원 번역** 기능도 제공합니다. **중요한 이유:** 내장된 도구는 개발자와 콘텐츠 작성자 간의 작업 흐름을 단축시켜 - 접착 코드가 줄고, 벤더 의존성이 감소합니다. --- ## 언제 어떤 것을 선택해야 할까요? - **react-intl**을 선택하세요, 만약 **ICU 우선** 메시지 포맷팅과 직관적이고 표준에 맞는 API를 원하며, 팀이 카탈로그와 안전성 검사를 수동으로 관리하는 데 익숙하다면. - **react-i18next**를 선택하세요, 만약 **i18next 생태계의 폭넓은 기능**(탐지기, 백엔드, ICU 플러그인, 통합 등)이 필요하고, 유연성을 얻기 위해 더 많은 설정을 감수할 수 있다면. - **Intlayer를 선택하세요** 만약 **컴포넌트 범위의 콘텐츠**, **엄격한 TypeScript**, **빌드 시 보장**, **트리 쉐이킹**, 그리고 **포함된 편집 도구**를 중요하게 생각한다면 - 특히 **크고 모듈화된** React 앱에 적합합니다. --- ## 실용적인 마이그레이션 노트 (react-intl / react-i18next → Intlayer) - **점진적으로 마이그레이션하세요**: 한 기능 또는 라우트부터 시작하고, 전환 기간 동안 기존 카탈로그를 병행 유지하세요. - **컴포넌트별 사전 사용을 채택하세요**: 콘텐츠를 컴포넌트와 함께 배치하여 결합도를 줄이세요. - **엄격한 검사 활성화**: 빌드 시 오류가 누락된 키/로케일을 CI 초기에 드러내도록 하세요. - **번들 크기 측정**: 사용하지 않는 문자열이 제거되면서 크기 감소를 기대하세요. --- ## 결론 세 가지 라이브러리 모두 React를 효과적으로 현지화합니다. 차별점은 **안전하고 확장 가능한** 환경을 구축하기 위해 얼마나 많은 **인프라**를 만들어야 하는가에 있습니다: - **Intlayer**는 **모듈화된 콘텐츠**, **엄격한 TS 타입 검사**, **빌드 시 안전성**, **트리 쉐이킹된 번들**, 그리고 **편집 도구**를 기본으로 제공하며, 이는 번거로운 작업이 아닙니다. - 팀이 다국어, 컴포넌트 중심의 React 앱에서 **유지보수성과 속도**를 중요시한다면, Intlayer는 오늘날 가장 **완벽한** 개발자 및 콘텐츠 워크플로우를 제공합니다.