📋 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>
This commit is contained in:
parent
6e8a7b81fb
commit
c3963fc26c
320
HEADPLANE_KOREAN_LOCALIZATION_PLAN.md
Normal file
320
HEADPLANE_KOREAN_LOCALIZATION_PLAN.md
Normal file
@ -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
|
||||||
Loading…
Reference in New Issue
Block a user