다국어 지원

HUA UX는 SSR 지원, 네임스페이스 조직, 쉬운 언어 전환을 제공하는 완전한 i18n 솔루션을 제공합니다.

라이브 데모

현재:

키: common:nav.home

결과: 홈

설정

// hua-ux.config.ts
import { defineConfig } from '@hua-labs/hua-ux/framework/config';

export default defineConfig({
  preset: 'product',

  i18n: {
    // Default language
    defaultLanguage: 'ko',

    // Supported languages
    supportedLanguages: ['ko', 'en', 'ja'],

    // Fallback when translation is missing
    fallbackLanguage: 'en',

    // Organize translations by namespace
    namespaces: ['common', 'home', 'about', 'products'],

    // Loading strategy: 'static' | 'api' | 'custom'
    translationLoader: 'static',
  },
});

번역 파일 구조

public/translations/
├── ko/
│   ├── common.json    # Shared translations (nav, buttons)
│   ├── home.json      # Homepage translations
│   └── about.json     # About page translations
├── en/
│   ├── common.json
│   ├── home.json
│   └── about.json
└── ja/
    ├── common.json
    ├── home.json
    └── about.json

예제: common.json

{
  "nav": {
    "home": "Home",
    "products": "Products",
    "about": "About"
  },
  "buttons": {
    "getStarted": "Get Started",
    "learnMore": "Learn More"
  }
}

사용법

기본 번역

import { useTranslation } from '@hua-labs/hua-ux';

function MyComponent() {
  const { t } = useTranslation();

  return (
    <div>
      {/* namespace:key format */}
      <h1>{t('home:hero.title')}</h1>
      <p>{t('common:buttons.learnMore')}</p>
    </div>
  );
}

보간법 사용

// Translation file
{
  "greeting": "Hello, {{name}}!",
  "items": "You have {{count}} items"
}

// Component
const { t } = useTranslation();
t('home:greeting', { name: 'John' }); // "Hello, John!"
t('home:items', { count: 5 });        // "You have 5 items"

언어 전환

import { useLanguageChange } from '@hua-labs/hua-ux';

function LanguageSwitcher() {
  const {
    currentLanguage,
    changeLanguage,
    supportedLanguages,
  } = useLanguageChange();

  return (
    <select
      value={currentLanguage}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      {supportedLanguages.map((lang) => (
        <option key={lang.code} value={lang.code}>
          {lang.nativeName}
        </option>
      ))}
    </select>
  );
}

서버 사이드 렌더링 (SSR)

SEO와 성능을 위해 서버에서 번역을 로드하세요:

// app/layout.tsx
import { HuaUxLayout } from '@hua-labs/hua-ux/framework';
import { getSSRTranslations } from '@hua-labs/hua-ux/framework/server';
import { setConfig } from '@hua-labs/hua-ux/framework/config';
import huaUxConfig from '../hua-ux.config';

setConfig(huaUxConfig);

export default async function RootLayout({ children }) {
  // Load translations on server
  const initialTranslations = await getSSRTranslations(
    huaUxConfig,
    'public/translations'
  );

  // Merge with config
  const configWithSSR = {
    ...huaUxConfig,
    i18n: {
      ...huaUxConfig.i18n,
      initialTranslations,
    },
  };

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

SSR 번역의 장점:

번역되지 않은 콘텐츠 깜빡임 없음 (FOUC)
더 나은 SEO - 검색 엔진이 번역된 콘텐츠를 볼 수 있음
더 빠른 초기 렌더링

모범 사례

1.네임스페이스 사용 - 페이지 또는 기능별로 번역 구성 (common, home, products)
2.공통 번역 분리 유지 - 네비게이션, 버튼, 공유 UI는 'common' 네임스페이스에
3.설명적인 키 사용 - 'title1'보다 'hero.title'이 더 좋음
4.폴백 언어 포함 - 번역이 누락된 경우 항상 영어를 폴백으로 사용
5.SSR 사용 - SEO와 성능을 위해 서버 사이드에서 번역 로드

지원 언어

ko한국어

enEnglish

ja日本語

zh中文

esEspañol

frFrançais

deDeutsch

ptPortuguês

모션 SDUI