headscale-tailscale-replacement/HEADPLANE_KOREAN_LOCALIZATION_PLAN.md

📋 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 환경변수로 쉽게 제어
• 현재 환경에서 즉시 적용 가능

단점:

• 제한적인 유연성
• 텍스트별 개별 환경변수 필요

구현 방법:

// 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. 브라우저 확장 스크립트 예시

// ==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 환경변수 설정 예시

# 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. 번역 파일 구조 예시

// 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