SSR Translations

함수

@hua-labs/hua

서버사이드에서 번역을 로드하여 언어 깜빡임을 방지합니다. 사용자 언어 설정이 있는 SSR 앱에 필수.

설치

Terminalbash

npm install @hua-labs/hua

Importtsx

import { SSR Translations } from '@hua-labs/hua';

개요

SSR Translations는 서버에서 모든 번역 데이터를 로드한 후 HTML을 클라이언트에 전달하여 언어 깜빡임을 제거하고 SEO를 개선합니다.

왜 SSR 번역인가?

깜빡임 없음

첫 렌더링부터 번역이 준비되어 로딩 상태가 불필요합니다

SEO 친화적

검색 엔진이 JavaScript 실행 없이 완전히 번역된 콘텐츠를 확인합니다

더 나은 성능

초기 번역을 위한 추가 클라이언트 사이드 API 호출이 없습니다

API 레퍼런스

옵션

이름	타입	기본값	설명
config*	HuaConfig	-	docs:i18n.ssr-translations.options.config
translationsDir	string	"translations"	docs:i18n.ssr-translations.options.translationsDir

반환값

이름	타입	설명
translations	Promise<Record<string, Record<string, Record<string, string>>>>	docs:i18n.ssr-translations.returns.translations

코드 예시

docs:common.basicUsage

tsx

// app/layout.tsx (Server Component)
import { HuaProvider } from '@hua-labs/hua/framework';
import { getSSRTranslations } from '@hua-labs/hua/framework/server';
import HuaConfig from '../hua.config';

export default async function RootLayout({ children }) {
  // Load all translations server-side
  const initialTranslations = await getSSRTranslations(HuaConfig);

  const configWithSSR = {
    ...HuaConfig,
    i18n: {
      ...HuaConfig.i18n,
      initialTranslations,  // ← Pre-loaded translations
    },
  };

  return (
    <html lang="ko">
      <body>
        <HuaProvider config={configWithSSR}>
          {children}
        </HuaProvider>
      </body>
    </html>
  );
}

docs:i18n.ssr-translations.examples.i18nexamplescustompath

tsx

// Custom translations directory
const initialTranslations = await getSSRTranslations(
  HuaConfig,
  'app/lib/translations'  // Custom path
);

// File structure:
// your-app/
// └── app/
//     └── lib/
//         └── translations/
//             ├── ko/
//             │   ├── common.json
//             │   └── navigation.json
//             └── en/
//                 ├── common.json
//                 └── navigation.json

docs:i18n.ssr-translations.examples.i18nexampleswithdblanguage

tsx

// SSR with database language preference
import { cookies, headers } from "next/headers";
import { auth } from "@/lib/auth";
import { getUserSettings } from "@/lib/user-settings-server";

export default async function RootLayout({ children }) {
  // Load translations and session in parallel
  const [initialTranslations, session] = await Promise.all([
    getSSRTranslations(HuaConfig),
    auth(),
  ]);

  // Determine language: DB > Cookie > Header > Default
  let language = 'ko';

  if (session?.user?.id) {
    const settings = await getUserSettings(session.user.id);
    if (settings?.language) {
      language = settings.language;
    }
  }

  // Fallback to cookie/header if not logged in
  if (language === 'ko') {
    const cookieStore = await cookies();
    const cookieLang = cookieStore.get('language')?.value;
    if (cookieLang) language = cookieLang;
  }

  return (
    <html lang={language}>
      <body>
        <HuaProvider
          config={{
            ...HuaConfig,
            i18n: {
              ...HuaConfig.i18n,
              initialTranslations,
              defaultLanguage: language,  // SSR language
            },
          }}
        >
          {children}
        </HuaProvider>
      </body>
    </html>
  );
}

docs:i18n.ssr-translations.examples.i18nexamplespreventflickering

tsx

/**
 * Why SSR Translations?
 * SSR 번역을 사용하는 이유
 *
 * Without SSR translations:
 * 1. Server renders with default language (ko)
 * 2. Client hydrates
 * 3. Client fetches translations
 * 4. Language switches → FLICKER! ⚡
 *
 * With SSR translations:
 * 1. Server loads translations
 * 2. Server renders with correct language
 * 3. Client hydrates with same translations
 * 4. No flicker ✅
 *
 * Benefits:
 * - No language flickering on page load
 * - SEO: Search engines see translated content immediately
 * - Better UX: Users see correct language from first paint
 * - Faster perceived load time
 */

사용 사례

깜빡임 방지

페이지 로드 시 언어 깜빡임 제거

SEO 최적화

검색 엔진이 올바른 언어를 즉시 인식

DB 언어 동기화

사용자 데이터베이스의 언어 설정과 동기화

Translation Loaders useTranslation