홈/i18nexus/Server Components

Server Components

Next.js 서버 컴포넌트에서 i18nexus 사용하기

개요

Next.js의 서버 컴포넌트에서는 useTranslation 훅을 사용할 수 없습니다. 대신 서버 전용 함수를 사용해야 합니다.

✓더 작은 JavaScript 번들

✓더 빠른 초기 로딩

✓더 나은 SEO

⚠동적 언어 전환 불가

서버 번역 API

getServerLanguage()

서버에서 쿠키로부터 현재 언어를 읽어옵니다.

import { headers } from "next/headers";
import { getServerLanguage } from "i18nexus/server";

export default async function Page() {
  const headersList = await headers();
  const language = getServerLanguage(headersList);

  console.log(language); // "ko" or "en"
}

createServerTranslation()

서버에서 사용할 번역 함수를 생성합니다.

import { createServerTranslation } from "i18nexus/server";
import { translations } from "@/locales";

export default async function Page() {
  const language = getServerLanguage(headersList);
  const t = createServerTranslation(language, translations);

  return <h1>{t("Welcome")}</h1>;
}

완전한 예제

import { headers } from "next/headers";
import { getServerLanguage, createServerTranslation } from "i18nexus/server";
import { translations } from "@/locales";

// ✅ 서버 컴포넌트 (기본값)
export default async function ServerPage() {
  // 1. 쿠키에서 언어 가져오기
  const headersList = await headers();
  const language = getServerLanguage(headersList);

  // 2. 번역 함수 생성
  const t = createServerTranslation(language, translations);

  // 3. 번역 사용
  return (
    <div>
      <h1>{t("Welcome")}</h1>
      <p>{t("This is a server component")}</p>
      <p>Current language: {language}</p>
    </div>
  );
}

서버 컴포넌트 vs 클라이언트 컴포넌트

🖥️서버 컴포넌트

✓더 작은 번들 크기

✓더 빠른 초기 로딩

✓더 나은 SEO

✓하이드레이션 불일치 없음

✗언어 전환 불가

✗클라이언트 상호작용 불가

createServerTranslation()

⚡클라이언트 컴포넌트

✓동적 언어 전환

✓완전한 상호작용

✓React 훅 사용 가능

✓이벤트 핸들러 사용

⚠더 큰 번들 크기

⚠'use client' 필요

useTranslation()

언제 사용해야 하나요?

✅서버 컴포넌트 사용

정적 콘텐츠 (블로그, 문서)
SEO가 중요한 페이지
초기 로딩 속도가 중요한 경우
사용자 상호작용이 필요 없는 페이지

⚡클라이언트 컴포넌트 사용

언어 선택기/전환 버튼
사용자 입력이 필요한 폼
동적으로 변경되는 콘텐츠
React 훅이 필요한 경우

하이브리드 접근법

서버 컴포넌트와 클라이언트 컴포넌트를 함께 사용하면 최적의 성능을 얻을 수 있습니다.

// app/page.tsx (서버 컴포넌트)
import { headers } from "next/headers";
import { getServerLanguage, createServerTranslation } from "i18nexus/server";
import { translations } from "@/locales";
import LanguageSwitcher from "./LanguageSwitcher"; // 클라이언트 컴포넌트

export default async function HomePage() {
  const headersList = await headers();
  const language = getServerLanguage(headersList);
  const t = createServerTranslation(language, translations);

  return (
    <div>
      {/* 클라이언트 컴포넌트: 언어 전환 */}
      <LanguageSwitcher />

      {/* 서버 컴포넌트: 정적 콘텐츠 */}
      <h1>{t("Welcome")}</h1>
      <p>{t("This content is rendered on the server")}</p>
    </div>
  );
}

// app/LanguageSwitcher.tsx (클라이언트 컴포넌트)
"use client";

import { useLanguageSwitcher } from "i18nexus";

export default function LanguageSwitcher() {
  const { currentLanguage, changeLanguage, availableLanguages } =
    useLanguageSwitcher();

  return (
    <div>
      {availableLanguages.map((lang) => (
        <button
          key={lang.code}
          onClick={() => changeLanguage(lang.code)}
        >
          {lang.name}
        </button>
      ))}
    </div>
  );
}

중요한 참고사항

💡하이드레이션 불일치 방지

서버와 클라이언트가 같은 언어를 사용하도록 쿠키에서 언어를 읽어야 합니다.

// layout.tsx에서
const headersList = await headers();
const language = getServerLanguage(headersList);

<I18nProvider initialLanguage={language}>

🔄언어 변경 시 페이지 리로드

서버 컴포넌트는 언어 변경 시 자동으로 업데이트되지 않습니다. 클라이언트 컴포넌트에서 언어를 변경하면 쿠키가 업데이트되고, 페이지를 새로고침하면 서버 컴포넌트도 새 언어로 렌더링됩니다.