생성:2024-03-07마지막 업데이트:2025-09-30

    Intlayer로 컴포넌트를 다국어(i18n)로 만드는 방법

    이 가이드는 두 가지 일반적인 환경에서 UI 컴포넌트를 다국어로 만드는 최소 단계를 보여줍니다:

    • React (Vite/SPA)
    • Next.js (App Router)

    먼저 콘텐츠를 선언한 후 컴포넌트에서 이를 가져옵니다.

    1) 콘텐츠 선언하기 (React 및 Next.js 공통)

    컴포넌트 근처에 콘텐츠 선언 파일을 만드세요. 이렇게 하면 번역이 사용되는 위치와 가까워지고 타입 안전성을 보장할 수 있습니다.

    import { t, type Dictionary } from "intlayer";

const componentContent = {
  key: "component-example",
  content: {
    title: t({
      en: "Hello",
      fr: "Bonjour",
      es: "Hola",
    }),
    description: t({
      en: "A multilingual React component",
      fr: "Un composant React multilingue",
      es: "Un componente React multilingüe",
    }),
  },
} satisfies Dictionary;

export default componentContent;

    구성 파일을 선호하는 경우 JSON도 지원됩니다.

    {
  "$schema": "https://intlayer.org/schema.json",
  "key": "component-example",
  "content": {
    "title": {
      "nodeType": "translation",
      "translation": { "en": "Hello", "fr": "Bonjour", "es": "Hola" }
    },
    "description": {
      "nodeType": "translation",
      "translation": {
        "en": "다국어 React 컴포넌트",
        "fr": "Un composant React multilingue",
        "es": "Un componente React multilingüe"
      }
    }
  }
}

    2) 콘텐츠를 가져오기

    경우 A. React 앱 (Vite/SPA)

    기본 접근법: 키로 검색하기 위해 useIntlayer를 사용합니다. 이렇게 하면 컴포넌트가 간결하고 타입이 지정됩니다.

    import { useIntlayer } from "react-intlayer";

export function ComponentExample() {
  const content = useIntlayer("component-example");
  return (
    <div>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
    </div>
  );
}

    서버 사이드 렌더링 또는 프로바이더 외부에서: 필요할 때 명시적인 locale을 전달하며 react-intlayer/server를 사용하세요.

    import { useIntlayer } from "react-intlayer/server";

export function ServerRenderedExample({ locale }: { locale: string }) {
  const content = useIntlayer("component-example", locale);
  return (
    <>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
    </>
  );
}

    대안: 호출 위치에서 구조를 함께 배치하는 것을 선호한다면 useDictionary를 사용하여 전체 선언된 객체를 읽을 수 있습니다.

    import { useDictionary } from "react-intlayer";
import componentContent from "./component.content";

export function ComponentWithDictionary() {
  const { title, description } = useDictionary(componentContent);
  return (
    <div>
      <h1>{title}</h1>
      <p>{description}</p>
    </div>
  );
}

    사례 B. Next.js (앱 라우터)

    데이터 안전성과 성능을 위해 서버 컴포넌트를 선호하세요. 서버 파일에서는 next-intlayer/server에서 useIntlayer를 사용하고, 클라이언트 컴포넌트에서는 next-intlayer에서 useIntlayer를 사용하세요.

    import { useIntlayer } from "next-intlayer/server";

export default function ServerComponent() {
  const content = useIntlayer("component-example");
  return (
    <>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
    </>
  );
}
    "use client";

import { useIntlayer } from "next-intlayer";

export function ClientComponent() {
  const content = useIntlayer("component-example");
  return (
    <div>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
    </div>
  );
}

    팁: 페이지 메타데이터 및 SEO를 위해 getIntlayer를 사용하여 콘텐츠를 가져오고 getMultilingualUrls를 통해 다국어 URL을 생성할 수도 있습니다.

    왜 Intlayer의 컴포넌트 접근법이 최선인가

    • 콜로케이션(Collocation): 콘텐츠 선언이 컴포넌트 근처에 위치하여 분산을 줄이고 디자인 시스템 전반에서 재사용성을 향상시킵니다.
    • 타입 안전성(Type safety): 키와 구조가 강력하게 타입 지정되어 있으며, 누락된 번역은 런타임이 아닌 빌드 타임에 감지됩니다.
    • 서버 우선(Server-first): 보안성과 성능 향상을 위해 서버 컴포넌트에서 네이티브로 작동하며, 클라이언트 훅은 여전히 사용하기 편리합니다.
    • 트리 쉐이킹(Tree-shaking): 컴포넌트에서 사용하는 콘텐츠만 번들에 포함되어 대규모 앱에서도 페이로드를 작게 유지합니다.
    • 개발자 경험(DX) 및 도구: 내장 미들웨어, SEO 도우미, 선택적 비주얼 에디터/AI 번역 기능이 일상 작업을 간소화합니다.

    Next.js 중심 비교 및 패턴은 다음 링크에서 확인하세요: https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer

    관련 가이드 및 참고 자료

    이 페이지들은 엔드 투 엔드 설정, 프로바이더, 라우팅, SEO 도우미를 포함합니다.

    Intlayer의 이점