# 📋 Headplane UI 한글화 계획서

## 🔍 현재 상황 분석

### Headplane 국제화 현황
- ❌ i18n 라이브러리 미사용 (react-i18next, next-intl 등 없음)
- ❌ 모든 UI 텍스트가 컴포넌트에 하드코딩
- ❌ 언어 설정 옵션 없음
- ❌ GitHub에 다국어 지원 요청이나 논의 없음

### 기술 스택
- ✅ React 19.1.0 + TypeScript
- ✅ Vite 빌드 시스템  
- ✅ Docker 멀티스테이지 빌드
- ✅ pnpm 패키지 매니저

### 현재 접속 정보
- **로컬**: http://localhost:3000/admin/
- **외부**: http://192.168.0.151:3000/admin/
- **API Key**: `8qRr1IB.tV95CmA0fLaCiGGIgBfeoN9daHceFkzI`

## 🎯 한글화 목표

### 우선순위 1: 핵심 UI 요소
- [ ] 상단 헤더 "Headplane" → "헤드플레인" 
- [ ] 네비게이션 메뉴 (Machines → 장치 관리, Users → 사용자 관리, Settings → 설정 등)
- [ ] 로그인 페이지 텍스트 (API Key → API 키, Sign In → 로그인)
- [ ] 메인 대시보드 라벨들

### 우선순위 2: 상세 페이지
- [ ] 테이블 헤더 (Name → 이름, IP Address → IP 주소, Status → 상태 등)
- [ ] 버튼 텍스트 (Create → 생성, Delete → 삭제, Edit → 편집 등)
- [ ] 폼 라벨 및 플레이스홀더

### 우선순위 3: 메시지 및 알림
- [ ] 에러 메시지
- [ ] 성공/확인 메시지
- [ ] 도움말 텍스트

## 🛠️ 구현 방안별 비교

### 방안 1: 환경 변수 기반 (권장 - 단기)
**난이도**: ⭐⭐  
**소요 시간**: 2-3시간  
**장점**: 
- 빠른 구현 가능
- 기존 코드 최소 변경
- Docker 환경변수로 쉽게 제어
- 현재 환경에서 즉시 적용 가능

**단점**: 
- 제한적인 유연성
- 텍스트별 개별 환경변수 필요

**구현 방법**:
```typescript
// app/config/texts.ts 생성
export const UI_TEXTS = {
  app_title: process.env.HEADPLANE_TITLE || 'Headplane',
  nav: {
    machines: process.env.HEADPLANE_NAV_MACHINES || 'Machines',
    users: process.env.HEADPLANE_NAV_USERS || 'Users',
    settings: process.env.HEADPLANE_NAV_SETTINGS || 'Settings'
  }
};
```

### 방안 2: react-i18next 도입 (권장 - 장기)
**난이도**: ⭐⭐⭐⭐  
**소요 시간**: 1-2일  
**장점**: 
- 완전한 국제화 지원
- 언어 전환 기능
- 표준적인 접근 방식
- 향후 확장성 좋음

**단점**: 
- 모든 컴포넌트 수정 필요
- 라이브러리 의존성 추가
- 상당한 코드 변경 필요

**구현 구조**:
```
public/locales/
├── en/
│   └── translation.json
└── ko/
    └── translation.json
```

### 방안 3: 브라우저 확장프로그램 (즉시 적용)
**난이도**: ⭐  
**소요 시간**: 30분  
**장점**: 
- 즉시 적용 가능
- 코드 수정 불필요
- 테스트 목적으로 최적

**단점**: 
- 개인 환경에서만 동작
- 동적 콘텐츠 한계
- 일시적 해결책

### 방안 4: 포크 후 하드코딩 수정
**난이도**: ⭐⭐⭐  
**소요 시간**: 4-6시간  
**장점**: 
- 완전한 제어
- 즉시 적용 가능

**단점**: 
- 업스트림 업데이트 어려움
- 유지보수 부담

## 📅 단계별 실행 계획

### Phase 1: 즉시 적용 (오늘)
#### 1-1. 브라우저 확장프로그램 제작
- [ ] Tampermonkey 스크립트 작성
- [ ] 핵심 UI 요소 번역 매핑
- [ ] 테스트 및 검증

#### 1-2. 브라우저 확장 스크립트 예시
```javascript
// ==UserScript==
// @name         Headplane 한글화
// @match        http://192.168.0.151:3000/*
// @match        http://localhost:3000/*
// ==/UserScript==

const translations = {
  'Headplane': '헤드플레인',
  'Machines': '장치 관리',
  'Users': '사용자 관리',
  'Settings': '설정',
  'API Key': 'API 키',
  'Sign In': '로그인',
  'Welcome to Headplane': '헤드플레인에 오신 것을 환영합니다',
  'Enter an API key to authenticate': 'API 키를 입력하여 인증해주세요'
};

function translatePage() {
  document.querySelectorAll('*').forEach(element => {
    if (element.children.length === 0 && element.textContent.trim()) {
      const text = element.textContent.trim();
      if (translations[text]) {
        element.textContent = translations[text];
      }
    }
  });
}

// 페이지 로드 시 번역 적용
translatePage();

// 동적 콘텐츠 변경 감지 및 번역 적용
new MutationObserver(translatePage).observe(document.body, {
  childList: true, 
  subtree: true
});
```

### Phase 2: 임시 해결책 (1-2일 내)
#### 2-1. 환경 변수 기반 커스터마이징
- [ ] 텍스트 상수 파일 생성 (`app/config/texts.ts`)
- [ ] 주요 컴포넌트에 텍스트 상수 적용
- [ ] Docker Compose 환경변수 설정
- [ ] 커스텀 Docker 이미지 빌드
- [ ] 컨테이너 재배포 및 테스트

#### 2-2. Docker 환경변수 설정 예시
```yaml
# docker-compose.yml에 추가
services:
  headplane:
    environment:
      - TZ=Asia/Seoul
      - HEADSCALE_URL=http://headscale:8080
      - HEADSCALE_API_KEY=${HEADSCALE_API_KEY}
      # 한글화 환경변수
      - HEADPLANE_TITLE=헤드플레인
      - HEADPLANE_NAV_MACHINES=장치 관리
      - HEADPLANE_NAV_USERS=사용자 관리
      - HEADPLANE_NAV_SETTINGS=설정
      - HEADPLANE_LOGIN_TITLE=로그인
      - HEADPLANE_API_KEY_LABEL=API 키
```

### Phase 3: 완전한 해결책 (1주일 내)
#### 3-1. react-i18next 라이브러리 도입
- [ ] GitHub에서 tale/headplane 포크
- [ ] 로컬 개발 환경 구성
- [ ] react-i18next 라이브러리 설치
- [ ] i18n 설정 및 번역 파일 구조 생성
- [ ] 주요 컴포넌트 국제화 적용
- [ ] 언어 전환 UI 추가
- [ ] 커스텀 Docker 이미지 빌드 및 배포

#### 3-2. 번역 파일 구조 예시
```json
// public/locales/ko/translation.json
{
  "app": {
    "title": "헤드플레인",
    "description": "헤드스케일 관리 웹 인터페이스"
  },
  "navigation": {
    "machines": "장치 관리",
    "users": "사용자 관리", 
    "settings": "설정",
    "accessControl": "접근 제어",
    "dns": "DNS"
  },
  "login": {
    "title": "헤드플레인에 오신 것을 환영합니다",
    "description": "API 키를 입력하여 헤드플레인에 인증해주세요.",
    "apiKeyLabel": "API 키",
    "apiKeyPlaceholder": "API 키를 입력해주세요",
    "signInButton": "로그인",
    "helpText": "터미널에서 'headscale apikeys create' 명령을 실행하여 API 키를 생성할 수 있습니다."
  },
  "machines": {
    "title": "장치 관리",
    "description": "테일넷에 연결된 장치들을 관리합니다.",
    "tableHeaders": {
      "name": "이름",
      "addresses": "주소",
      "version": "버전",
      "lastSeen": "마지막 접속"
    }
  },
  "users": {
    "title": "사용자 관리",
    "description": "헤드스케일 사용자들을 관리합니다."
  }
}
```

## 🎯 권장 실행 방안

### 즉시 실행: 방안 3 (브라우저 확장프로그램)
현재 사용 중인 환경에서 바로 한글 UI를 확인할 수 있도록 **Tampermonkey 스크립트**부터 시작

### 단기 목표: 방안 1 (환경 변수 기반)
Docker 환경변수를 통한 텍스트 커스터마이징으로 **안정적인 한글화** 구현

### 장기 목표: 방안 2 (react-i18next 도입)
완전한 국제화 지원을 위한 **표준적인 다국어 지원** 구현

## 📊 예상 번역 범위

### 핵심 번역 대상 (총 약 50-80개 텍스트)

#### 공통 UI 요소
- Headplane → 헤드플레인
- API Key → API 키  
- Sign In → 로그인
- Settings → 설정
- Profile → 프로필
- Logout → 로그아웃

#### 네비게이션 메뉴
- Machines → 장치 관리
- Users → 사용자 관리
- Access Control → 접근 제어
- DNS → DNS 설정

#### 테이블 및 폼 요소
- Name → 이름
- IP Address → IP 주소
- Status → 상태
- Version → 버전
- Last Seen → 마지막 접속
- Create → 생성
- Delete → 삭제
- Edit → 편집

## 🚀 시작하기

### 1단계: 브라우저 확장프로그램 설치
1. Chrome/Edge에서 Tampermonkey 확장프로그램 설치
2. 위의 스크립트 코드를 새 스크립트로 생성
3. http://192.168.0.151:3000/admin/ 접속하여 한글화 확인

### 2단계: 환경변수 기반 구현 준비
1. tale/headplane 저장소 포크
2. 로컬 개발환경 구성
3. 텍스트 상수 파일 생성 및 적용

## 📝 진행 상황 체크리스트

### Phase 1: 브라우저 확장프로그램
- [ ] Tampermonkey 설치 및 스크립트 작성
- [ ] 로그인 페이지 한글화 테스트
- [ ] 메인 대시보드 한글화 테스트
- [ ] 번역 품질 검증

### Phase 2: 환경변수 기반
- [ ] 프로젝트 포크 및 클론
- [ ] 개발 환경 구성
- [ ] 텍스트 상수 파일 구조 설계
- [ ] 주요 컴포넌트 수정
- [ ] Docker 이미지 빌드 테스트
- [ ] 프로덕션 배포

### Phase 3: react-i18next 도입
- [ ] i18n 라이브러리 설치 및 설정
- [ ] 번역 파일 구조 생성
- [ ] 컴포넌트별 국제화 적용
- [ ] 언어 전환 UI 구현
- [ ] 전체 테스트 및 검증

## 🔗 관련 링크

- **Headplane GitHub**: https://github.com/tale/headplane
- **React i18next 문서**: https://react.i18next.com/
- **현재 Headplane UI**: http://192.168.0.151:3000/admin/

## 📅 생성일: 2025-09-09
## 👤 작성자: Claude Code Assistant