📋 Add Headplane Korean localization plan

- Comprehensive analysis of current Headplane i18n status - 4 different implementation approaches with pros/cons - Phase-by-phase implementation plan (browser extension → env vars → react-i18next) - Detailed Korean translation mappings for UI elements - Implementation examples and code snippets - Progress checklist for tracking localization work Ready to start with browser extension approach for immediate Korean UI. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-09 15:24:04 +09:00 · 2025-09-09 15:24:04 +09:00 · c3963fc26c
commit c3963fc26c
parent 6e8a7b81fb
1 changed files with 320 additions and 0 deletions
--- a/HEADPLANE_KOREAN_LOCALIZATION_PLAN.md
+++ b/HEADPLANE_KOREAN_LOCALIZATION_PLAN.md
@ -0,0 +1,320 @@
+# 📋 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