LiteLLM Admin UI

i18n 한글화 전체 범위 시각화

BerriAI/litellm fork → ui/litellm-dashboard에 i18n 인프라 신설 → 한국어 locale 추가

작성일 2026-06-09 자동화율 ~95% (jscodeshift) 키 추정 1,000~1,800개 네임스페이스 14~20개
전체 개요
아키텍처
컴포넌트 맵
작업 순서
커버리지
자동화 도구
용어 사전

프로젝트 핵심 요약

📊 작업 규모 at a Glance

41+
컴포넌트 도메인 폴더
1,000~1,800
추정 번역 키
~95%
자동화 가능 (jscodeshift)
4명
병렬 작업 가능 인원

✓ 스코프 IN

  • LiteLLM Admin UI 정적 텍스트 한글화 (영문 fallback 유지)
  • AntD 컴포넌트 한국어 locale 적용 (DatePicker, Pagination 등)
  • 한국어 폰트 적용 (Inter → Pretendard/Noto Sans KR)
  • 효성 ITX/IB 로고·파비콘·컬러·헤더 래핑
  • 효성 운영 동선 메뉴만 활성화
  • 빌드 파이프라인 + 폐쇄망 배포 절차 문서

✗ 스코프 OUT

  • LiteLLM proxy(Python) 응답·검증 메시지 한글화
  • LLM 응답 자체 한글화
  • 새 메뉴/페이지 추가
  • 효성 내부 시스템(SSO/DB/네트워크) 연결
  • LiteLLM 자체 기능/로직 수정

모노레포 구조 & 빌드 흐름

BerriAI/litellm Monorepo

LiteLLM 공식 저장소 - Python proxy + Next.js Admin UI

litellm/proxy/ Python

FastAPI 기반 LLM Gateway Proxy

  • _experimental/out/ ← 빌드된 UI 정적 파일
  • /ui 라우트로 Admin UI 서빙
  • DISABLE_ADMIN_UI=true로 비활성화 가능

ui/litellm-dashboard/ 작업 대상

Next.js 16 + React 18 Admin UI

  • package.json (i18n 라이브러리 0개)
  • src/app/ (라우트 7개)
  • src/components/ (도메인 41+개)
  • build_ui.sh (빌드 스크립트)

빌드 흐름

build_ui.sh
→
next build
→
out/
→
_experimental/out/
정적 export → Python 패키지에 포함 → Docker 이미지화

의존성 스택

⚛️ Core Framework

  • React 18.3.1
  • Next.js 16.2.6
  • TypeScript 5.9.3

🎨 UI Libraries

  • Ant Design 5.29.3 locale 설정
  • Tremor 3.18.7
  • Tailwind CSS 3.4.19
  • Lucide React 0.513.0

🌐 i18n (추가 필요)

  • react-i18next 신규 추가
  • i18next 신규 추가
  • i18next-browser-languagedetector 신규 추가
  • dayjs/locale/ko 설정 추가

컴포넌트 마이그레이션 우선순위

P0: 일상 운영 화면
P1: 정책·권한
P2: 확장 기능
P3: 부가/실험
P0 일상 운영 화면
Navbar/5 components
VirtualKeysPage/key 관리
view_users/사용자 목록
team/팀 관리
UsagePage/사용량 대시보드
model_dashboard/모델 현황
view_logs/로그 조회
Settings/3 sub-domains
P1 정책·권한
budgets/예산 관리
view_model/모델 상세
add_model/모델 추가
model_add/모델 등록
AccessGroups/접근 그룹
permissions/권한 설정
organization/조직 관리
P2 확장 기능
mcp_tools/MCP 도구
mcp_server_management/MCP 서버
vector_store_management/벡터 스토어
guardrails/가드레일
policies/정책
prompts/프롬프트
tag_management/태그
cache_settings/캐시
router_settings/라우터
P3 부가/실험 (숨김 후보)
playground/API 테스트
chat/채팅 UI
agents/에이전트
agent_management/에이전트 관리
workflow_runs/워크플로우
AIHub/AI Hub
Projects/프로젝트
MemoryView/메모리 뷰

🔧 공용 컴포넌트 (전체 영향)

atoms/ molecules/ organisms/ templates/ common_components/ shared/ ui/ key_team_helpers/

병렬 작업 구조 & 작업 순서

🔀 병렬 작업 전제조건

⚠️ 선행 필수
  • 1. 용어 사전 합의 완료
  • 2. 네임스페이스 구조 확정
  • 3. i18n 인프라 셋업 (1명)
📁 용어 사전 위치
docs/i18n/TERMINOLOGY-AGREEMENT.md

이 문서 합의 전에는 각자 번역 시작하면 안 됨. 용어 불일치 발생.

Git Branch 전략

📊 Branch 구조
main
└─ feature/i18n-infra ← 인프라 담당 (선행)
├─ feature/i18n-common ← 담당 A
├─ feature/i18n-keys-usage ← 담당 B
├─ feature/i18n-teams-models ← 담당 C
└─ feature/i18n-budgets-access ← 담당 D
🔄 Merge 순서
1st i18n-infra → main 인프라 확정
2nd i18n-common → main 공통 NS 확정
3rd B, C, D 순차 머지 충돌 최소화
Final 통합 검증 후 release 빌드 통과
🗂️ 파일 충돌 방지 규칙
Branch 담당 파일 (독점) 공유 파일 (주의)
i18n-infra lib/i18n/*, layout.tsx, AntdGlobalProvider.tsx package.json ← 선행 확정
i18n-common locales/*/common.json, Navbar/* 없음
i18n-keys-usage locales/*/keys.json, usage.json, logs.json
VirtualKeysPage/*, UsagePage/*, view_logs/*		 common.json import 시 참조만
i18n-teams-models locales/*/teams.json, models.json, settings.json
team/*, view_users/*, model_dashboard/*, Settings/*		 common.json import 시 참조만
i18n-budgets-access locales/*/budgets.json, access.json, permissions.json
budgets/*, AccessGroups/*, permissions/*, organization/*		 common.json import 시 참조만

⚠️ 각 브랜치는 자기 담당 locale 파일과 컴포넌트만 수정. common.json은 담당 A만 수정하고 나머지는 import만 함.

💻 각 담당자 작업 시작 명령어
# 담당 A (인프라 + common)
git checkout -b feature/i18n-infra main
git checkout -b feature/i18n-common feature/i18n-infra
# 담당 B (keys, usage, logs)
git fetch origin feature/i18n-infra
git checkout -b feature/i18n-keys-usage origin/feature/i18n-infra
# 담당 C (teams, models, settings)
git fetch origin feature/i18n-infra
git checkout -b feature/i18n-teams-models origin/feature/i18n-infra
# 담당 D (budgets, access, permissions)
git fetch origin feature/i18n-infra
git checkout -b feature/i18n-budgets-access origin/feature/i18n-infra

📌 모든 feature 브랜치는 i18n-infra가 머지된 후 시작. infra 브랜치에서 분기해야 i18n 설정 포함.

병렬 작업 분할 (담당자별)

A 인프라 담당
i18n 라이브러리 설치선행
Provider 구성선행
AntD locale 연동선행
폰트 교체 (Pretendard)선행
jscodeshift transform 작성병렬
B P0 컴포넌트 (일상 운영)
Navbar/5 files
VirtualKeysPage/key 관리
UsagePage/사용량
view_logs/로그
C P0 컴포넌트 (팀/사용자)
view_users/사용자 목록
team/팀 관리
model_dashboard/모델
Settings/3 sub
D P1 컴포넌트 (정책/권한)
budgets/예산
AccessGroups/접근
permissions/권한
organization/조직

작업 흐름 (커버리지 중심)

0 선행: 용어 합의 & 인프라

feature/i18n-infra 브랜치에서 작업. 머지 후 다른 담당자 시작.

TERMINOLOGY-AGREEMENT.md 리뷰 & 확정~60개 용어
i18n 라이브러리 설치 (react-i18next)3개 패키지
lib/i18n/index.ts, Provider 구성infra 독점
jscodeshift transform 작성 & 테스트5개 패턴
PR → main 머지 → 다른 브랜치 분기 가능Gate

1 영문 리터럴 추출 & 키 생성

feature/i18n-common 브랜치. 담당 A가 전체 키 추출 후 NS별 분배.

JSX children 추출 (Title, Text, Button 등)~400개
props 텍스트 추출 (title, label, placeholder)~500개
Table headers, notifications~300개
키 자동 부여 → NS별 en.json 생성1,200+ 키
각 NS의 en.json을 담당자에게 전달배분

2 병렬: 번역 + codemod 변환

각 담당자가 자기 브랜치에서 독립 작업. 파일 충돌 없음.

i18n-common 담당 A: common.json + Navbar/*~80 키
i18n-keys-usage 담당 B: keys/usage/logs.json + 컴포넌트~250 키
i18n-teams-models 담당 C: teams/models/settings.json + 컴포넌트~300 키
i18n-budgets-access 담당 D: budgets/access/permissions.json + 컴포넌트~200 키

3 순차 머지 & 빌드 검증

충돌 최소화 위해 순서대로 머지. 각 PR 후 빌드 확인.

i18n-common → main (공통 NS 확정)1st merge
i18n-keys-usage → main2nd merge
i18n-teams-models → main3rd merge
i18n-budgets-access → main4th merge
next build 통과 & LSP 에러 0Gate

4 검수 & 효성 래핑

전체 통합 후 화면별 검수. 브랜딩 적용.

P0 화면 검수 (8개 도메인)일상 운영
P1 화면 검수 (7개 도메인)정책/권한
효성 ITX/IB 로고, 파비콘, 컬러설정 기반
P2/P3 메뉴 숨김 (enabled_ui_pages 설정)YAML

5 Release 빌드 & 배포

release/i18n-v1.0 태그 생성. Docker 이미지 빌드.

git tag release/i18n-v1.0버전 고정
build_ui.sh → _experimental/out/정적 빌드
효성 Docker 이미지 교체out/ 교체
폐쇄망 tar 추출/전송ghcr.io 대안

네임스페이스별 번역 키 추정

1,000~1,800
총 추정 키 수
14~20
네임스페이스
41+
컴포넌트 폴더
0%
현재 i18n 커버리지
Namespace 추정 키 수 대상 도메인 복잡도
common 50~80 Navbar, 공통 버튼·라벨
auth 20~30 login, onboarding
keys 80~120 VirtualKeysPage, KeyAliasSelect, DeletedKeysPage
teams 60~100 team, view_users, organization
models 80~120 model_dashboard, model_add, add_model, view_model
usage 60~100 UsagePage, EntityUsageExport, CostTracking
budgets 40~60 budgets
mcp 60~100 mcp_tools, mcp_server_management
guardrails 40~60 guardrails, GuardrailsMonitor
settings 80~120 Settings (AdminSettings 포함)
playground 40~60 playground, chat
logs 40~60 view_logs
기타 300~500 tag/vector_store/cache/policy/routing/workflow/agents/AIHub/Projects

텍스트 패턴 유형

📝 JSX Children

<Title>Key Ownership</Title>

🏷️ Props (title, label)

<Tooltip title="Select who...">

📊 Table Headers

header: "Model Name"

🔔 Notifications

NotificationsManager.success("...")

📋 Form Labels

<Form.Item label="User Email">

💬 Modal Titles

<Modal title="Create New Key">

자동화 도구 & Codemod 전략

🛠️ 권장 도구 조합

⚡ jscodeshift (Primary)

Facebook의 AST 기반 코드 변환 도구. 95% 자동 변환 가능

  • JSX children → t() 변환 95%
  • Props 문자열 변환 95%
  • AntD Form labels 90%
  • Table headers 95%

📦 i18next-cli (Secondary)

키 추출 전용. 다국어 카탈로그 생성

  • 번역 키 추출 70%
  • JSON 카탈로그 생성 자동
  • 누락 키 탐지 자동

🔧 Manual Review

자동화 불가 영역. 수동 검토 필요

  • 동적 문자열 10%
  • 템플릿 리터럴 30%
  • 컨텍스트 의존 20%

AST 변환 패턴 (5가지 핵심)

Pattern 1: JSX Text Children

// Before
<Title>Key Ownership</Title>
// After
<Title>{t('keys.ownership')}</Title>

Pattern 2: JSX String Props

// Before
<Input placeholder="Enter name" />
// After
<Input placeholder={t('form.enterName')} />

Pattern 3: AntD Form Labels

// Before
<Form.Item label={<span>Email</span>}>
// After
<Form.Item label={t('form.email')}>

Pattern 4: Table Headers

// Before
{ header: "Model Name", key: "model" }
// After
{ header: t('models.name'), key: "model" }

자동화 커버리지 매트릭스

카테고리 자동화율 도구 예상 소요
JSX text children 95% jscodeshift 자동
JSX string props 95% jscodeshift 자동
AntD form labels 90% jscodeshift 자동
Table headers 95% jscodeshift 자동
Object properties 90% jscodeshift 자동
동적 문자열 10% 수동 High
템플릿 리터럴 30% 수동 Medium
전체 평균 ~95% Hybrid 15~20h

✅ 권장 CLI 명령어

# Dry run (안전 - 실제 변경 없음)
jscodeshift -t codemods/jsx-to-i18n.js 'src/**/*.tsx' --dry --print
# 실제 실행
jscodeshift -t codemods/jsx-to-i18n.js 'src/**/*.tsx' --parser=tsx --cpus=4
# 키 추출
i18next 'src/**/*.tsx' -c i18next.config.js

LLM 용어 한글화 사전

litemaas 참고 + 효성 맥락 적용

📚 핵심 LLM/Gateway 용어

English Korean (권장) 비고
Virtual Key가상 키API 키 대신 사용하는 프록시 키
Spend지출비용/사용량 맥락
Budget예산할당된 비용 한도
Soft Budget소프트 예산경고만, 차단 안 함
Hard Budget하드 예산초과 시 차단
Guardrail가드레일안전 장치/제한
RPM분당 요청 수 (RPM)약어 유지 + 설명
TPM분당 토큰 수 (TPM)약어 유지 + 설명
Token토큰LLM 처리 단위
Prompt Token프롬프트 토큰입력 토큰
Completion Token완성 토큰출력 토큰

👥 사용자/권한 용어

English Korean (권장) 비고
Team팀
Organization조직
Admin관리자
Internal User내부 사용자
Proxy Admin프록시 관리자
Admin Approval관리자 승인
Access Group접근 그룹
Permission권한
SSOSSO (싱글 사인온)약어 유지
SCIMSCIM프로토콜명 유지

📊 모델/사용량 용어

English Korean (권장) 비고
Model모델
Endpoint엔드포인트
Provider제공자OpenAI, Azure 등
Fallback폴백대체 모델
Usage사용량
Request요청
Response응답
Latency지연 시간
Throughput처리량
Cache캐시

🔧 설정/기능 용어

English Korean (권장) 비고
Settings설정
Configuration구성
Dashboard대시보드
Logs로그
Playground플레이그라운드
MCPMCPModel Context Protocol
Vector Store벡터 스토어
Router라우터
Pass-Through패스스루
Webhook웹훅

📋 용어 사전 출처

rh-aiservices-bu/litemaas

  • • 102KB 한국어 locale (2,059 lines)
  • • ~1,200+ 번역 키
  • • 99.3% 번역 완성도
  • • PatternFly 기반 (별도 제품)

효성 맥락 적용 필요

  • • 효성 ITX/IB 기존 용어 확인
  • • 내부 스타일 가이드 반영
  • • CTO/실무자 컨펌 필요
  • • O-J (용어 사전) 미해결 항목