Leva를 활용한 다국어 지원 컨트롤 패널 구현 가이드

Leva는 React 중심의 GUI 컴포넌트 라이브러리로, 개발자가 매력적인 파라미터 제어 패널을 쉽게 만들 수 있도록 돕습니다. 전세계 사용자를 대상으로 하는 프로젝트가 증가함에 따라 다국어 지원은 필수적입니다. 본 가이드에서는 Leva 컨트롤 패널에 다국어 기능을 추가하는 방법을 자세히 살펴보겠습니다.

Leva 다국어 핵심 개념

Leva 컨트롤 패널의 다국어화는 크게 세 가지 요소로 나눌 수 있습니다: 레이블 번역, 툴팁 로컬라이제이션, 그리고 선택 옵션 다국어화. 이 과정에서 Leva 자체에는 내장된 다국어 기능이 없으므로 React와 연동하여 이를 구현할 수 있습니다.

레이블 다국어 처리

각 입력 요소는 사용자 정의 가능한 레이블을 제공합니다. 이를 위해 react-i18next 또는 react-intl 같은 다국어 라이브러리를 통합하면 동적으로 레이블을 설정할 수 있습니다.

import { useTranslation } from 'react-i18next';
import { useControls } from 'leva';

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

  const controls = useControls({
    [t('labels.brightness')]: { value: 0.5, min: 0, max: 1 },
    [t('labels.color')]: '#ff005b',
    [t('labels.position')]: { value: [0, 2, 12] }
  });

  return controls;
}

툴팁 다국어화

Leva는 각 컨트롤에 hint 속성을 추가할 수 있어 보조 정보를 제공하는 데 유용합니다. 이 속성도 다국어 라이브러리를 통해 다국어화할 수 있습니다.

const controls = useControls({
  quality: {
    value: 'high',
    options: ['low', 'medium', 'high'],
    hint: t('hints.qualitySelection')
  },
  animationSpeed: {
    value: 1.0,
    min: 0.1,
    max: 5.0,
    hint: t('hints.speedAdjustment')
  }
});

폴더 구조 다국어화

복잡한 컨트롤 패널의 경우 관련 요소들을 폴더로 그룹화하는 것이 일반적입니다. 폴더 이름도 번역되어야 하며 다음과 같이 구현할 수 있습니다.

import { folder } from 'leva';

const controls = useControls(t('folders.visualSettings'), {
  [t('folders.lighting')]: folder({
    [t('labels.ambientLight')]: 0.5,
    [t('labels.directionalLight')]: 1.0
  }),
  [t('labels.shadows')]: folder({
    [t('labels.shadowQuality')]: 'high',
    [t('labels.shadowResolution')]: 2048
  })
});

실시간 언어 전환

실시간으로 언어를 변경하려면 언어 변경을 감지하고 Leva 패널을 재렌더링해야 합니다. 아래는 완전한 구현 예시입니다.

import React, { useEffect, useState } from 'react';
import { useControls, Leva } from 'leva';
import { useTranslation } from 'react-i18next';

function DynamicLanguagePanel() {
  const { t, i18n } = useTranslation();
  const [language, setLanguage] = useState(i18n.language);

  useEffect(() => {
    const handleLanguageChange = () => {
      setLanguage(i18n.language);
    };

    i18n.on('languageChanged', handleLanguageChange);
    return () => i18n.off('languageChanged', handleLanguageChange);
  }, [i18n]);

  const controls = useControls({
    [t('labels.language')]: {
      value: language,
      options: ['en', 'ko', 'fr', 'es', 'de'],
      onChange: (value) => i18n.changeLanguage(value)
    },
    [t('labels.volume')]: { value: 0.7, min: 0, max: 1 },
    [t('labels.theme')]: { value: 'dark', options: ['light', 'dark', 'auto'] }
  }, [language]);

  return <Leva key={language} />;
}

선택형 입력 요소 다국어화

선택형 입력 요소의 옵션도 다국어 처리가 필요합니다. 아래는 최선의 방법입니다.

const qualityOptions = {
  [t('options.low')]: 'low',
  [t('options.medium')]: 'medium',
  [t('options.high')]: 'high',
  [t('options.ultra')]: 'ultra'
};

const controls = useControls({
  [t('labels.graphicsQuality')]: {
    value: 'high',
    options: qualityOptions
  },
  [t('labels.resolutionScale')]: {
    value: 1.0,
    min: 0.5,
    max: 2.0,
    step: 0.1
  }
});

버튼 및 버튼 그룹 다국어화

버튼과 버튼 그룹도 다국어 처리가 필요합니다.

const { resetSettings } = useControls({
  [t('buttons.actions')]: {
    [t('buttons.reset')]: () => resetAllSettings(),
    [t('buttons.save')]: () => saveCurrentSettings(),
    [t('buttons.load')]: () => loadDefaultSettings()
  }
});

테마 및 스타일 다국어 고려사항

다국어화 시 각 언어별 텍스트 길이 차이도 고려해야 합니다.

import { Leva } from 'leva';

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

  return (
    <>
      <Leva 
        theme={{
          colors: {
            accent1: i18n.language === 'ar' ? '#ff6b6b' : '#007acc',
            accent2: i18n.language === 'ar' ? '#ffa726' : '#4ecdc4'
          }
        }}
        oneLineLabels={i18n.language !== 'de'}
      />
      {/* 애플리케이션 내용 */}
    </>
  );
}

플러그인 다국어화

커스텀 플러그인에서도 다국어를 지원해야 합니다.

import { useInputContext } from 'leva';
import { useTranslation } from 'react-i18next';

function CustomPluginComponent() {
  const { label, value, onChange } = useInputContext();
  const { t } = useTranslation();

  return (
    <div>
      <label>{typeof label === 'string' ? t(label) : label}</label>
      <input 
        type="text" 
        value={value}
        onChange={(e) => onChange(e.target.value)}
        placeholder={t('plugins.custom.placeholder')}
      />
    </div>
  );
}

성능 최적화

다국어화는 실행 시간 오버헤드를 증가시키므로 다음 전략을 사용해 성능을 유지하세요.

React.memo 사용: 불필요한 리렌더링 방지
번역 파일 조건부 로드: 현재 언어만 로드
결과 캐싱: 자주 사용되는 번역 결과 캐싱
useMemo 활용: 다국어화된 구성 객체 캐싱

테스트 및 품질 보증

완료 후 모든 언어에서 정상 작동하는지 확인해야 합니다.

언어 전환 테스트
텍스트 오버플로우 검사
RTL 언어 지원
특수 문자 처리
날짜 및 시간 형식

배포 및 유지 관리

생산 환경으로 배포할 때는 다음 사항을 고려하세요.

번역 추출: 번역 파일 자동 생성
CDN 호스팅: 로딩 속도 개선
자동 언어 감지: 브라우저 설정 기반 언어 선택
Fallback 언어 설정
번역 업데이트 절차

권장 도구

react-i18next: 가장 포괄적인 React 다국어 라이브러리
format.js: Facebook의 국제화 라이브러리
i18next-browser-languagedetector: 브라우저 언어 자동 감지
i18next-http-backend: 서버로부터 번역 파일 로드

이 가이드를 통해 Leva 컨트롤 패널에 다국어 기능을 추가하는 방법을 배웠습니다. 이제 글로벌 사용자를 위한 서비스를 제공할 준비가 되었습니다.

태그: Leva React Internationalization

6월 16일 22:00에 게시됨

괴물 클럽