React 국제화 (i18n) react-i18next 및 Intlayer와 함께

개요

• Intlayer는 구성 요소 수준의 콘텐츠 선언 파일을 통해 번역 관리를 도와줍니다.
• react-i18next는 i18next에 대한 인기 있는 React 통합으로, useTranslation과 같은 후크를 제공하여 구성 요소에서 지역화된 문자열을 가져옵니다.

결합하면, Intlayer는 i18next 호환 JSON 사전을 내보내기하므로 react-i18next가 런타임에서 이를 소비할 수 있습니다.

왜 react-i18next와 함께 Intlayer를 사용해야 할까요?

Intlayer 콘텐츠 선언 파일은 다음과 같은 장점으로 더 나은 개발자 경험을 제공합니다.

1. 파일 배치의 유연성
   각 콘텐츠 선언 파일을 필요로 하는 구성 요소 바로 옆에 배치하세요. 이 구조는 번역을 함께 보관할 수 있어, 구성 요소가 이동하거나 삭제될 때 고립된 번역이 발생하지 않도록 합니다.

   bash

   .└── src    └── components        └── MyComponent            ├── index.content.ts # 콘텐츠 선언 파일            └── index.tsx

2. 중앙 집중식 번역
   단일 콘텐츠 선언 파일이 구성 요소에 필요한 모든 번역을 수집하여 누락된 번역을 쉽게 식별할 수 있게 합니다.
   TypeScript를 사용하면 번역이 누락될 경우 컴파일 타임 오류도 발생합니다.

설치

Create React App 프로젝트에서 다음 종속성을 설치하세요:

# npm으로npm install intlayer react-i18next i18next i18next-resources-to-backend

# yarn으로yarn add intlayer react-i18next i18next i18next-resources-to-backend

# pnpm으로pnpm add intlayer react-i18next i18next i18next-resources-to-backend

이 패키지들은 무엇인가요?

• intlayer – i18n 구성, 콘텐츠 선언 관리 및 사전 출력을 구축하기 위한 CLI 및 핵심 라이브러리입니다.
• react-intlayer – 사전 구축 자동화를 위한 스크립트를 제공하는 Intlayer의 React 전용 통합입니다.
• react-i18next – i18next를 위한 React 전용 통합 라이브러리로, useTranslation 후크를 포함합니다.
• i18next – 번역 처리를 위한 기본 프레임워크입니다.
• i18next-resources-to-backend – JSON 리소스를 동적으로 가져오는 i18next 백엔드입니다.

Intlayer를 구성하여 i18next 사전 내보내기

프로젝트의 최상위에 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"],    // 생성된 리소스의 출력 디렉토리 선택    // 이 폴더는 아직 존재하지 않는 경우 생성됩니다.    i18nextResourcesDir: "./i18next/resources",  },};export default config;

참고: TypeScript를 사용하지 않는 경우, 이 구성 파일을 .cjs, .mjs 또는 .js로 생성할 수 있습니다 (자세한 내용은 Intlayer 문서를 참조하세요).

i18next 리소스 구축

콘텐츠 선언이 준비된 후 (다음 섹션), Intlayer 빌드 명령을 실행하세요:

# npm으로npx run intlayer build

# yarn으로yarn intlayer build

# pnpm으로pnpm intlayer build

이렇게 하면 기본적으로 ./i18next/resources 디렉토리에 i18next 리소스가 생성됩니다.

일반적인 출력 예시는 다음과 같습니다:

.└── i18next    └── resources       ├── ko       │   └── my-content.json       ├── fr       │   └── my-content.json       └── es           └── my-content.json

각 Intlayer 선언 키는 i18next 네임스페이스로 사용됩니다 (예: my-content.json).

react-i18next 구성에 사전을 가져오기

런타임에서 이러한 리소스를 동적으로 로드하려면 i18next-resources-to-backend를 사용하세요. 예를 들어, 프로젝트에 i18n.ts (또는 .js) 파일을 생성하세요:

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;

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;

그런 다음 루트 또는 인덱스 파일 (예: src/index.tsx)에서 App을 렌더링하기 전에 이 i18n 설정을 가져옵니다:

import React from "react";import ReactDOM from "react-dom/client";// 아무것도 하기 전에 i18n 초기화import "./i18n";import App from "./App";ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(  <React.StrictMode>    <App />  </React.StrictMode>);

콘텐츠 선언 작성 및 관리

Intlayer는 ./src 아래에 위치한 "콘텐츠 선언 파일"에서 번역을 추출합니다 (기본값).
여기 TypeScript의 최소 예시가 있습니다:

import { t, type DeclarationContent } from "intlayer";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...",    }),  },} satisfies DeclarationContent;export default content;

JSON, .cjs 또는 .mjs를 선호하는 경우 Intlayer 문서를 참조하세요.

기본적으로 유효한 콘텐츠 선언은 파일 확장자 패턴과 일치합니다:
*.content.{ts,tsx,js,jsx,mjs,cjs,json}

React 구성 요소에서 번역 사용하기

Intlayer 리소스를 구축하고 react-i18next를 구성한 후, react-i18next에서 useTranslation 후크를 직접 사용할 수 있습니다.
예를 들면:

import { 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>  );};export default MyComponent;

t 함수는 생성된 JSON 내부의 키를 참조한다는 점에 유의하세요. Intlayer 콘텐츠 항목 이름이 heading인 경우, t("heading")을 사용합니다.

선택 사항: Create React App 스크립트와 통합 (CRACO)

react-intlayer는 사용자 정의 빌드 및 개발 서버 구성을 위한 CRACO 기반 접근 방식을 제공합니다. Intlayer의 빌드 단계를 원활하게 통합하고 싶다면:

1. react-intlayer 설치 (아직 설치하지 않았다면): bash npm install react-intlayer --save-dev

2. package.json 스크립트를 조정하여 react-intlayer 스크립트를 사용하세요:

   jsonc

   "scripts": {  "start": "react-intlayer start",  "build": "react-intlayer build",  "transpile": "intlayer build"}

   react-intlayer 스크립트는 CRACO를 기반으로 합니다. 또한 intlayer craco 플러그인을 기반으로 한 자신의 설정을 구현할 수 있습니다. 여기에서 예시 확인.

이제 npm run build, yarn build 또는 pnpm build를 실행하면 Intlayer와 CRA 빌드를 모두 트리거할 수 있습니다.

TypeScript 구성

Intlayer는 콘텐츠에 대한 자동 생성된 타입 정의를 제공합니다. TypeScript가 이를 인식하도록 하려면, types (또는 다르게 구성한 경우 types)를 tsconfig.json include 배열에 추가하세요:

{  "compilerOptions": {    // ...  },  "include": ["src", "types"],}

이렇게 하면 TypeScript가 번역의 형식을 추론하여 더 나은 자동 완성과 오류 감지를 제공합니다.

Git 구성

자동 생성된 파일과 폴더를 Intlayer에서 무시하는 것이 좋습니다. 다음 줄을 .gitignore에 추가하세요:

# Intlayer에 의해 생성된 파일 무시.intlayeri18next

이러한 리소스나 .intlayer 내부 빌드 아티팩트를 커밋하지 않는 것이 일반적입니다, 왜냐하면 이들은 매 빌드마다 재생성될 수 있기 때문입니다.