@hua-labs/i18n-core

v1.1.0-alpha.3

i18n

SSR

SSR/CSR 완벽 지원, 깜박임 없는 국제화 핵심 라이브러리. Next.js App Router 최적화.

$npm install @hua-labs/i18n-core

주요 기능

제로 플리커

SSR 초기 데이터로 깜박임 없는 언어 전환

SSR/CSR 지원

Next.js App Router와 완벽 호환

네임스페이스

번역 파일을 모듈별로 분리 관리

동적 로딩

필요한 번역만 동적으로 로드

제공 Hooks

useTranslation

번역 함수와 현재 언어 상태를 제공

useLanguageChange

언어 변경 함수와 지원 언어 목록 제공

useI18n

모든 i18n 기능을 제공하는 통합 훅

빠른 시작

1. 번역 파일 준비

json

// public/translations/ko/common.json
{
  "welcome": "안녕하세요",
  "greeting": "{{name}}님, 환영합니다!"
}

// public/translations/en/common.json
{
  "welcome": "Hello",
  "greeting": "Welcome, {{name}}!"
}

2. Provider 설정

tsx

// app/layout.tsx (with hua-ux)
import { HuaUxLayout } from '@hua-labs/hua-ux/framework';
import { getSSRTranslations } from '@hua-labs/hua-ux/framework/server';

const config = {
  i18n: {
    defaultLanguage: 'ko',
    supportedLanguages: ['ko', 'en'],
    namespaces: ['common'],
    translationLoader: 'static',
  },
};

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

  return (
    <HuaUxLayout config={{ ...config, i18n: { ...config.i18n, initialTranslations } }}>
      {children}
    </HuaUxLayout>
  );
}

3. 번역 사용

tsx

'use client';

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

function MyComponent() {
  const { t, tWithParams, currentLanguage } = useTranslation();

  return (
    <div>
      <h1>{t('common:welcome')}</h1>
      <p>{tWithParams('common:greeting', { name: 'User' })}</p>
      <p>Current: {currentLanguage}</p>
    </div>
  );
}

4. 언어 변경

tsx

'use client';

import { useTranslation, useLanguageChange } from '@hua-labs/i18n-core';

function LanguageSelector() {
  const { currentLanguage } = useTranslation();
  const { 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 || lang.name}
        </option>
      ))}
    </select>
  );
}

API Reference

useTranslation()

반환값	Type	설명
t	(key: string) => string	번역 함수
tWithParams	(key, params) => string	파라미터가 있는 번역
currentLanguage	string	현재 언어 코드
setLanguage	(lang: string) => void	언어 설정 함수
isLoading	boolean	로딩 상태
isInitialized	boolean	초기화 완료 여부

useLanguageChange()

반환값	Type	설명
currentLanguage	string	현재 언어 코드
changeLanguage	(lang: string) => void	언어 변경 함수 (검증 포함)
supportedLanguages	{ code, name, nativeName }[]	지원 언어 목록

기본 지원 언어 (11개)

다음 11개 언어에 대한 메타데이터가 기본 제공됩니다. 커스텀 언어도 쉽게 추가할 수 있습니다.

한국어

English

en-IN

English (IN)

日本語

简体中文

zh-TW

繁體中文

Español

Français

Deutsch

Русский

pt / it

+확장 가능