next-i18next와 Intlayer를 활용한 Next.js 국제화(i18n)

목차

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 블로그 게시물에서 next-intl과의 구체적인 비교를 확인하세요.

왜 Intlayer를 next-i18next와 결합해야 하나요?

Intlayer가 훌륭한 독립형 i18n 솔루션을 제공하지만(자세한 내용은 Next.js 통합 가이드 참조), 다음과 같은 여러 이유로 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단계: 의존성 설치

선호하는 패키지 관리자를 사용하여 필요한 패키지를 설치하세요:

npm install intlayer @intlayer/sync-json-plugin

패키지 설명:

• intlayer: 콘텐츠 선언 및 관리를 위한 핵심 라이브러리
• @intlayer/sync-json-plugin: Intlayer 콘텐츠 선언을 i18next JSON 형식과 동기화하는 플러그인

2단계: JSON을 래핑하기 위한 Intlayer 플러그인 구현

지원하는 로케일을 정의하기 위해 Intlayer 구성 파일을 만듭니다:

i18next용 JSON 사전도 내보내고 싶다면, syncJSON 플러그인을 추가하세요:

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({      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 플러그인 문서를 참조하세요.

(선택 사항) 3단계: 컴포넌트별 JSON 번역 구현

기본적으로 Intlayer는 JSON 파일과 콘텐츠 선언 파일을 모두 로드, 병합 및 동기화합니다. 자세한 내용은 콘텐츠 선언 문서를 참조하세요. 하지만 원한다면 Intlayer 플러그인을 사용하여 코드베이스 어디에서나 지역화된 JSON을 컴포넌트별로 관리할 수도 있습니다.

이를 위해 loadJSON 플러그인을 사용할 수 있습니다.

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({      source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,      priority: 0,    }),  ],};export default config;

이 설정은 src 디렉토리 내에서 {key}.i18n.json 패턴과 일치하는 모든 JSON 파일을 로드하여 Intlayer 사전으로 불러옵니다.

Git 구성

생성된 파일을 버전 관리에서 제외하세요:

# Intlayer에서 생성된 파일 무시.intlayerintl

이 파일들은 빌드 과정에서 자동으로 다시 생성되므로 저장소에 커밋할 필요가 없습니다.

VS Code 확장 프로그램

개발자 경험 향상을 위해 공식 Intlayer VS Code 확장 프로그램을 설치하세요:

VS Code 마켓플레이스에서 설치하기

개발자 경험을 향상시키기 위해 공식 Intlayer VS Code 확장 프로그램을 설치하세요:

VS Code 마켓플레이스에서 설치하기