# 다국어 관리 시스템 가이드

## 📋 목차

1. [시스템 개요](#시스템-개요)
2. [아키텍처 구조](#아키텍처-구조)
3. [데이터베이스 구조](#데이터베이스-구조)
4. [핵심 컴포넌트](#핵심-컴포넌트)
5. [사용법 가이드](#사용법-가이드)
6. [페이지 적용 방법](#페이지-적용-방법)
7. [새로운 다국어 키 추가](#새로운-다국어-키-추가)
8. [문제 해결](#문제-해결)
9. [모범 사례](#모범-사례)

## 🎯 시스템 개요

### 다국어 시스템이란?

현재 ERP 시스템은 한국어와 영어를 지원하는 다국어 시스템을 구축하고 있습니다. 사용자가 설정한 언어에 따라 UI의 모든 텍스트가 자동으로 번역되어 표시됩니다.

### 지원 언어

- **한국어 (KR)**: 기본 언어
- **영어 (US)**: 사용자 설정 가능

### 주요 특징

- **실시간 번역**: 페이지 로드 시 즉시 번역 적용
- **배치 처리**: 여러 키를 한 번에 조회하여 성능 최적화
- **캐싱 시스템**: 번역 결과를 메모리에 캐싱하여 중복 요청 방지
- **폴백 시스템**: 번역 실패 시 기본 텍스트 표시

## 🏗️ 아키텍처 구조

### 전체 구조도

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ useMultiLang│ │    │ │ Multilang   │ │    │ │ multilang   │ │
│ │ Hook        │ │    │ │ Controller  │ │    │ │ Table       │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ Multilang   │ │    │ │ Multilang   │ │    │ │ lang_keys   │ │
│ │ Utils       │ │    │ │ Service     │ │    │ │ Table       │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ UI          │ │    │ │ Batch API   │ │    │ │ translations│ │
│ │ Components  │ │    │ │ Endpoint    │ │    │ │ Table       │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### 데이터 흐름

1. **사용자 언어 설정**: `useMultiLang` 훅에서 사용자 언어 확인
2. **다국어 키 정의**: 컴포넌트에서 필요한 다국어 키 상수 정의
3. **배치 요청**: 여러 키를 한 번에 백엔드로 전송
4. **번역 조회**: 백엔드에서 데이터베이스에서 번역 데이터 조회
5. **결과 반환**: 번역된 텍스트를 프론트엔드로 반환
6. **UI 업데이트**: 번역된 텍스트로 컴포넌트 렌더링

## 🗄️ 데이터베이스 구조

### 실제 테이블 구조

#### 1. language_master (언어 마스터)

```sql
CREATE TABLE public.language_master (
  lang_code varchar(10) NOT NULL PRIMARY KEY,    -- 언어 코드 (KR, US)
  lang_name varchar(50) NOT NULL,                -- 언어명 (Korean, English)
  lang_native varchar(50) NOT NULL,              -- 원어명 (한국어, English)
  is_active bpchar(1) DEFAULT 'Y',               -- 활성화 여부
  sort_order int4 DEFAULT 0,                     -- 정렬 순서
  created_date timestamp DEFAULT CURRENT_TIMESTAMP,
  created_by varchar(50),
  updated_date timestamp DEFAULT CURRENT_TIMESTAMP,
  updated_by varchar(50)
);
```

#### 2. multi_lang_key_master (다국어 키 마스터)

```sql
CREATE TABLE public.multi_lang_key_master (
  key_id serial4 NOT NULL PRIMARY KEY,           -- 키 ID (자동 증가)
  company_code varchar(20) DEFAULT '*' NOT NULL, -- 회사 코드 (* = 공통)
  lang_key varchar(100) NOT NULL,                -- 다국어 키 (예: button.add)
  description text,                              -- 키 설명
  is_active bpchar(1) DEFAULT 'Y',               -- 활성화 여부
  menu_name varchar(50),                         -- 메뉴명 (다국어 관리 화면에 어디에서 쓰이는지 보여지는 용도. 한국어로 어느 메뉴에 쓰이는지 작성)
  created_date timestamp DEFAULT CURRENT_TIMESTAMP,
  created_by varchar(50),
  updated_date timestamp DEFAULT CURRENT_TIMESTAMP,
  updated_by varchar(50),
  CONSTRAINT uk_lang_key_company UNIQUE (company_code, lang_key)
);
```

#### 3. multi_lang_text (다국어 텍스트)

```sql
CREATE TABLE public.multi_lang_text (
  text_id serial4 NOT NULL PRIMARY KEY,          -- 텍스트 ID (자동 증가)
  key_id int4 NOT NULL,                          -- 키 마스터의 key_id
  lang_code varchar(10) NOT NULL,                -- 언어 코드 (KR, US)
  lang_text text NOT NULL,                       -- 번역된 텍스트
  is_active bpchar(1) DEFAULT 'Y',               -- 활성화 여부
  created_date timestamp DEFAULT CURRENT_TIMESTAMP,
  created_by varchar(50),
  updated_date timestamp DEFAULT CURRENT_TIMESTAMP,
  updated_by varchar(50),
  CONSTRAINT multi_lang_text_key_id_lang_code_key UNIQUE (key_id, lang_code),
  CONSTRAINT multi_lang_text_key_id_fkey FOREIGN KEY (key_id)
    REFERENCES multi_lang_key_master(key_id) ON DELETE CASCADE,
  CONSTRAINT multi_lang_text_lang_code_fkey FOREIGN KEY (lang_code)
    REFERENCES language_master(lang_code)
);
```

### 테이블 관계도

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  language_master │    │multi_lang_key_  │    │ multi_lang_text │
│                 │    │     master      │    │                 │
│ - lang_code     │    │ - key_id        │    │ - text_id       │
│ - lang_name     │    │ - company_code  │    │ - lang_key      │
│ - lang_native   │    │ - description   │    │ - key_id        │
│ - is_active     │    │ - is_active     │    │ - lang_code     │
│ - sort_order    │    │ - created_date  │    │ - lang_text     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │   외래키 관계    │
                        │                 │
                        │ lang_code       │
                        │ key_id          │
                        └─────────────────┘
```

### 데이터 저장 예시

#### 1. 언어 마스터 데이터

```sql
INSERT INTO language_master (lang_code, lang_name, lang_native) VALUES
('KR', 'Korean', '한국어'),
('US', 'English', 'English');
```

#### 2. 다국어 키 등록

```sql
INSERT INTO multi_lang_key_master (lang_key, company_code, description) VALUES
('button.add', '*', '추가 버튼'),
('button.edit', '*', '수정 버튼'),
('menu.title', '*', '메뉴 제목');
```

#### 3. 번역 텍스트 등록

```sql
-- 한국어 번역
INSERT INTO multi_lang_text (key_id, lang_code, lang_text)
SELECT km.key_id, 'KR',
  CASE km.lang_key
    WHEN 'button.add' THEN '추가'
    WHEN 'button.edit' THEN '수정'
    WHEN 'menu.title' THEN '메뉴 관리'
  END
FROM multi_lang_key_master km
WHERE km.lang_key IN ('button.add', 'button.edit', 'menu.title')
  AND km.company_code = '*';

-- 영어 번역
INSERT INTO multi_lang_text (key_id, lang_code, lang_text)
SELECT km.key_id, 'US',
  CASE km.lang_key
    WHEN 'button.add' THEN 'Add'
    WHEN 'button.edit' THEN 'Edit'
    WHEN 'menu.title' THEN 'Menu Management'
  END
FROM multi_lang_key_master km
WHERE km.lang_key IN ('button.add', 'button.edit', 'menu.title')
  AND km.company_code = '*';
```

## 🔧 핵심 컴포넌트

### 1. useMultiLang 훅

```typescript
// frontend/hooks/useMultiLang.ts
export const useMultiLang = (options: { companyCode?: string } = {}) => {
  const [userLang, setUserLang] = useState<string | null>(null);

  // 사용자 언어 조회 및 설정
  // 전역 언어 상태 동기화
  // 언어 변경 처리

  return {
    userLang, // 현재 사용자 언어 (KR, US)
    getText, // 다국어 텍스트 조회 함수
    changeLang, // 언어 변경 함수
    companyCode, // 회사 코드
  };
};
```

**주요 기능:**

- 사용자 언어 설정 및 조회
- 전역 언어 상태 관리
- 언어 변경 시 자동 동기화

**사용 예시:**

```typescript
const { userLang, getText, changeLang } = useMultiLang({ companyCode: "*" });

// 언어 변경
await changeLang("US");

// 다국어 텍스트 조회
const text = await getText("menu.management", "button.add");
```

### 2. Multilang Utils

```typescript
// frontend/lib/utils/multilang.ts
export const MENU_MANAGEMENT_KEYS = {
  TITLE: "menu.management.title",
  BUTTON_ADD: "button.add",
  BUTTON_EDIT: "button.edit",
  // ... 더 많은 키들
} as const;

// 배치 조회 함수
export async function getMultilangText(
  key: string,
  companyCode: string = "*",
  menuCode: string = "MENU_MANAGEMENT",
  userLang: string = "KR"
): Promise<string>;

// 동기 조회 함수 (캐시에서만)
export function getMultilangTextSync(
  key: string,
  companyCode: string = "*",
  menuCode: string = "MENU_MANAGEMENT",
  userLang: string = "KR"
): string;
```

**주요 기능:**

- 다국어 키 상수 정의
- 배치 처리로 성능 최적화
- 캐싱 시스템으로 중복 요청 방지
- 동기/비동기 조회 지원

### 3. Backend API

```typescript
// backend/src/controllers/multilangController.ts
@Post("/batch")
async getBatchTranslations(
  @Body() body: { langKeys: string[] },
  @Query() query: { companyCode: string; menuCode: string; userLang: string }
): Promise<ApiResponse<Record<string, string>>>
```

**API 엔드포인트:**

- **POST** `/multilang/batch` - 여러 키를 한 번에 조회
- **GET** `/multilang/:key` - 개별 키 조회 (사용하지 않음)

**요청 파라미터:**

```typescript
{
  langKeys: ["button.add", "button.edit", "menu.title"],
  companyCode: "*",        // 회사 코드 (* = 전체)
  menuCode: "MENU_MANAGEMENT", // 메뉴 코드
  userLang: "KR"           // 사용자 언어
}
```

**응답 형식:**

```typescript
{
  success: true,
  data: {
    "button.add": "추가",
    "button.edit": "수정",
    "menu.title": "메뉴 관리"
  }
}
```

## 📖 사용법 가이드

### 1. 기본 사용법

#### 단계별 가이드

1. **다국어 키 상수 정의**
2. **컴포넌트에서 다국어 텍스트 로드**
3. **UI에 번역된 텍스트 적용**

#### 예시 코드

```typescript
// 1. 다국어 키 상수 정의
const MENU_KEYS = ["menu.title", "button.add", "button.edit"];

// 2. 다국어 텍스트 로드
const [uiTexts, setUiTexts] = useState<Record<string, string>>({});

useEffect(() => {
  const loadTexts = async () => {
    const response = await apiClient.post("/multilang/batch", {
      langKeys: MENU_KEYS,
      companyCode: "*",
      menuCode: "MENU_MANAGEMENT",
      userLang: userLang,
    });

    if (response.data.success) {
      setUiTexts(response.data.data);
    }
  };

  if (userLang) {
    loadTexts();
  }
}, [userLang]);

// 3. UI에 적용
const getText = (key: string) => uiTexts[key] || key;

return (
  <div>
    <h1>{getText("menu.title")}</h1>
    <button>{getText("button.add")}</button>
  </div>
);
```

### 2. 고급 사용법

#### 배치 처리 최적화

```typescript
// 여러 키를 한 번에 조회하여 API 호출 최소화
const LANG_KEYS = [
  "form.title",
  "form.name.label",
  "form.name.placeholder",
  "form.submit.button",
];

// 한 번의 API 호출로 모든 키 조회
const translations = await getMultilangTextBatch(LANG_KEYS);
```

#### 폴백 시스템

```typescript
const getText = (key: string, fallback?: string) => {
  // 1. 번역된 텍스트 우선
  if (uiTexts[key]) return uiTexts[key];

  // 2. 폴백 텍스트 사용
  if (fallback) return fallback;

  // 3. 키 자체 반환 (디버깅용)
  return key;
};
```

## 🚀 페이지 적용 방법

### 1. 새로운 페이지에 다국어 적용하기

#### Step 1: 다국어 키 정의

```typescript
// constants/pageKeys.ts
export const PAGE_KEYS = {
  // 페이지 제목
  TITLE: "page.title",
  DESCRIPTION: "page.description",

  // 폼 요소
  FORM_NAME: "form.name",
  FORM_EMAIL: "form.email",
  FORM_SUBMIT: "form.submit",

  // 메시지
  SUCCESS_MESSAGE: "message.success",
  ERROR_MESSAGE: "message.error",
} as const;
```

#### Step 2: 컴포넌트에서 다국어 텍스트 로드

```typescript
// components/MyPage.tsx
import { PAGE_KEYS } from "@/constants/pageKeys";

export const MyPage: React.FC = () => {
  const { userLang } = useMultiLang();
  const [uiTexts, setUiTexts] = useState<Record<string, string>>({});

  // 다국어 텍스트 로드
  useEffect(() => {
    const loadTexts = async () => {
      if (!userLang) return;

      const response = await apiClient.post("/multilang/batch", {
        langKeys: Object.values(PAGE_KEYS),
        companyCode: "*",
        menuCode: "MY_PAGE",
        userLang: userLang,
      });

      if (response.data.success) {
        setUiTexts(response.data.data);
      }
    };

    loadTexts();
  }, [userLang]);

  // 텍스트 가져오기 함수
  const getText = (key: string) => uiTexts[key] || key;

  return (
    <div>
      <h1>{getText(PAGE_KEYS.TITLE)}</h1>
      <p>{getText(PAGE_KEYS.DESCRIPTION)}</p>

      <form>
        <label>{getText(PAGE_KEYS.FORM_NAME)}</label>
        <input placeholder={getText(PAGE_KEYS.FORM_NAME)} />

        <button type="submit">{getText(PAGE_KEYS.FORM_SUBMIT)}</button>
      </form>
    </div>
  );
};
```

#### Step 3: 데이터베이스에 번역 데이터 등록

```sql
-- 1. 다국어 키 마스터에 키 등록
INSERT INTO multi_lang_key_master (
  lang_key,
  company_code,
  description,
  is_active,
  created_date,
  created_by
) VALUES
('page.title', '*', '페이지 제목', 'Y', now(), 'system'),
('page.description', '*', '페이지 설명', 'Y', now(), 'system'),
('form.name', '*', '이름', 'Y', now(), 'system'),
('form.email', '*', '이메일', 'Y', now(), 'system'),
('form.submit', '*', '제출', 'Y', now(), 'system');

-- 2. 한국어 번역 텍스트 등록
INSERT INTO multi_lang_text (
  key_id,
  lang_code,
  lang_text,
  is_active,
  created_date,
  created_by
)
SELECT
  km.key_id,
  'KR',
  CASE km.lang_key
    WHEN 'page.title' THEN '내 페이지'
    WHEN 'page.description' THEN '이것은 내 페이지입니다'
    WHEN 'form.name' THEN '이름'
    WHEN 'form.email' THEN '이메일'
    WHEN 'form.submit' THEN '제출'
  END,
  'Y',
  now(),
  'system'
FROM multi_lang_key_master km
WHERE km.lang_key IN ('page.title', 'page.description', 'form.name', 'form.email', 'form.submit')
  AND km.company_code = '*';

-- 3. 영어 번역 텍스트 등록
INSERT INTO multi_lang_text (
  key_id,
  lang_code,
  lang_text,
  is_active,
  created_date,
  created_by
)
SELECT
  km.key_id,
  'US',
  CASE km.lang_key
    WHEN 'page.title' THEN 'My Page'
    WHEN 'page.description' THEN 'This is my page'
    WHEN 'form.name' THEN 'Name'
    WHEN 'form.email' THEN 'Email'
    WHEN 'form.submit' THEN 'Submit'
  END,
  'Y',
  now(),
  'system'
FROM multi_lang_key_master km
WHERE km.lang_key IN ('page.title', 'page.description', 'form.name', 'form.email', 'form.submit')
  AND km.company_code = '*';
```

### 2. 기존 페이지에 다국어 적용하기

#### Step 1: 하드코딩된 텍스트 찾기

```typescript
// 변경 전
return (
  <div>
    <h1>메뉴 관리</h1>
    <button>추가</button>
    <button>수정</button>
  </div>
);

// 변경 후
return (
  <div>
    <h1>{getText("menu.management.title")}</h1>
    <button>{getText("button.add")}</button>
    <button>{getText("button.edit")}</button>
  </div>
);
```

#### Step 2: 다국어 키 상수 추가

```typescript
// 기존 키에 새로운 키 추가
export const EXISTING_KEYS = [
  // 기존 키들...
  "menu.management.title",
  "button.add",
  "button.edit",
];
```

#### Step 3: 번역 데이터 등록

```sql
-- 1. 다국어 키 마스터에 키 등록
INSERT INTO multi_lang_key_master (
  lang_key,
  company_code,
  description,
  is_active,
  created_date,
  created_by
) VALUES
('menu.management.title', '*', '메뉴 관리 제목', 'Y', now(), 'system'),
('button.add', '*', '추가 버튼', 'Y', now(), 'system'),
('button.edit', '*', '수정 버튼', 'Y', now(), 'system');

-- 2. 한국어 번역 텍스트 등록
INSERT INTO multi_lang_text (
  key_id,
  lang_code,
  lang_text,
  is_active,
  created_date,
  created_by
)
SELECT
  km.key_id,
  'KR',
  CASE km.lang_key
    WHEN 'menu.management.title' THEN '메뉴 관리'
    WHEN 'button.add' THEN '추가'
    WHEN 'button.edit' THEN '수정'
  END,
  'Y',
  now(),
  'system'
FROM multi_lang_key_master km
WHERE km.lang_key IN ('menu.management.title', 'button.add', 'button.edit')
  AND km.company_code = '*';

-- 3. 영어 번역 텍스트 등록
INSERT INTO multi_lang_text (
  key_id,
  lang_code,
  lang_text,
  is_active,
  created_date,
  created_by
)
SELECT
  km.key_id,
  'US',
  CASE km.lang_key
    WHEN 'menu.management.title' THEN 'Menu Management'
    WHEN 'button.add' THEN 'Add'
    WHEN 'button.edit' THEN 'Edit'
  END,
  'Y',
  now(),
  'system'
FROM multi_lang_key_master km
WHERE km.lang_key IN ('menu.management.title', 'button.add', 'button.edit')
  AND km.company_code = '*';
```

## ➕ 새로운 다국어 키 추가

### 1. 프론트엔드에서 키 추가

#### Step 1: 키 상수 정의

```typescript
// constants/multilang.ts
export const NEW_FEATURE_KEYS = {
  // 새로운 기능 관련 키들
  FEATURE_TITLE: "new.feature.title",
  FEATURE_DESCRIPTION: "new.feature.description",
  FEATURE_BUTTON: "new.feature.button",
} as const;
```

#### Step 2: 컴포넌트에서 사용

```typescript
import { NEW_FEATURE_KEYS } from "@/constants/multilang";

const MyComponent = () => {
  const getText = (key: string) => uiTexts[key] || key;

  return (
    <div>
      <h2>{getText(NEW_FEATURE_KEYS.FEATURE_TITLE)}</h2>
      <p>{getText(NEW_FEATURE_KEYS.FEATURE_DESCRIPTION)}</p>
      <button>{getText(NEW_FEATURE_KEYS.FEATURE_BUTTON)}</button>
    </div>
  );
};
```

### 2. 백엔드에서 번역 데이터 등록

#### Step 1: 다국어 키 등록

```sql
-- multi_lang_key_master 테이블에 새로운 키 등록
INSERT INTO multi_lang_key_master (
  lang_key,
  company_code,
  description,
  is_active,
  created_date,
  created_by
) VALUES
('new.feature.title', '*', '새로운 기능 제목', 'Y', now(), 'system'),
('new.feature.description', '*', '새로운 기능 설명', 'Y', now(), 'system'),
('new.feature.button', '*', '새로운 기능 버튼', 'Y', now(), 'system');
```

#### Step 2: 번역 텍스트 등록

```sql
-- 한국어 번역 텍스트 등록
INSERT INTO multi_lang_text (
  key_id,
  lang_code,
  lang_text,
  is_active,
  created_date,
  created_by
)
SELECT
  km.key_id,
  'KR',
  CASE km.lang_key
    WHEN 'new.feature.title' THEN '새로운 기능'
    WHEN 'new.feature.description' THEN '이것은 새로운 기능입니다'
    WHEN 'new.feature.button' THEN '시작하기'
  END,
  'Y',
  now(),
  'system'
FROM multi_lang_key_master km
WHERE km.lang_key IN ('new.feature.title', 'new.feature.description', 'new.feature.button')
  AND km.company_code = '*';

-- 영어 번역 텍스트 등록
INSERT INTO multi_lang_text (
  key_id,
  lang_code,
  lang_text,
  is_active,
  created_date,
  created_by
)
SELECT
  km.key_id,
  'US',
  CASE km.lang_key
    WHEN 'new.feature.title' THEN 'New Feature'
    WHEN 'new.feature.description' THEN 'This is a new feature'
    WHEN 'new.feature.button' THEN 'Get Started'
  END,
  'Y',
  now(),
  'system'
FROM multi_lang_key_master km
WHERE km.lang_key IN ('new.feature.title', 'new.feature.description', 'new.feature.button')
  AND km.company_code = '*';
```

## 🔍 문제 해결

### 1. 일반적인 문제들

#### 문제: 키가 그대로 표시됨

```typescript
// 문제 상황
<h1>menu.management.title</h1>;

// 원인: 번역 데이터가 로드되지 않음
// 해결: 다국어 텍스트 로드 확인
console.log("uiTexts:", uiTexts);
console.log("userLang:", userLang);
```

#### 문제: 일부만 번역됨

```typescript
// 원인: 일부 키만 번역 데이터에 등록됨
// 해결: 모든 키에 대한 번역 데이터 확인
SELECT km.lang_key, t.lang_code, t.lang_text
FROM multi_lang_key_master km
LEFT JOIN multi_lang_text t ON km.key_id = t.key_id
WHERE km.lang_key IN ('key1', 'key2', 'key3')
  AND km.company_code = '*';
```

#### 문제: 언어 변경이 반영되지 않음

```typescript
// 원인: useMultiLang 훅의 의존성 배열 문제
// 해결: userLang 변경 시 다국어 텍스트 재로드
useEffect(() => {
  if (userLang) {
    loadTexts();
  }
}, [userLang]); // userLang 의존성 추가
```

### 2. 디버깅 방법

#### 콘솔 로그 확인

```typescript
// 다국어 텍스트 로드 과정 추적
console.log("🌐 다국어 텍스트 로드 시작:", {
  userLang,
  keys: MENU_KEYS,
  uiTextsCount: Object.keys(uiTexts).length,
});

// API 응답 확인
console.log("📡 API 응답:", response.data);

// 최종 상태 확인
console.log("✅ 최종 uiTexts:", uiTexts);
```

#### 네트워크 탭 확인

- **API 호출**: `/multilang/batch` 엔드포인트 호출 확인
- **요청 파라미터**: langKeys, companyCode, menuCode, userLang 확인
- **응답 데이터**: 번역된 텍스트가 올바르게 반환되는지 확인

#### 데이터베이스 직접 확인

```sql
-- 특정 키의 번역 데이터 확인
SELECT km.lang_key, t.lang_code, t.lang_text, km.description
FROM multi_lang_key_master km
LEFT JOIN multi_lang_text t ON km.key_id = t.key_id
WHERE km.lang_key = 'button.add'
  AND km.company_code = '*'
  AND t.lang_code = 'KR';

-- 특정 회사의 모든 번역 데이터 확인
SELECT km.lang_key, t.lang_code, t.lang_text, km.description
FROM multi_lang_key_master km
LEFT JOIN multi_lang_text t ON km.key_id = t.key_id
WHERE km.company_code = '*'
  AND t.lang_code = 'KR';
```

## 📚 모범 사례

### 1. 키 명명 규칙

#### 계층 구조 사용

```typescript
// 좋은 예시
export const KEYS = {
  // 페이지 레벨
  PAGE_TITLE: "page.title",
  PAGE_DESCRIPTION: "page.description",

  // 폼 레벨
  FORM_TITLE: "form.title",
  FORM_NAME: "form.name",
  FORM_EMAIL: "form.email",

  // 버튼 레벨
  BUTTON_SUBMIT: "button.submit",
  BUTTON_CANCEL: "button.cancel",

  // 메시지 레벨
  MESSAGE_SUCCESS: "message.success",
  MESSAGE_ERROR: "message.error",
};
```

#### 일관된 접두사 사용

```typescript
// 일관된 접두사로 그룹화
export const KEYS = {
  // 공통 UI 요소
  COMMON_LOADING: "common.loading",
  COMMON_ERROR: "common.error",
  COMMON_SUCCESS: "common.success",

  // 특정 기능
  FEATURE_TITLE: "feature.title",
  FEATURE_DESCRIPTION: "feature.description",
};
```

### 2. 성능 최적화

#### 배치 처리 사용

```typescript
// ❌ 나쁜 예시: 개별 요청
const text1 = await getText("key1");
const text2 = await getText("key2");
const text3 = await getText("key3");

// ✅ 좋은 예시: 배치 요청
const keys = ["key1", "key2", "key3"];
const translations = await getBatchTexts(keys);
```

#### 캐싱 활용

```typescript
// 번역 결과를 상태에 저장하여 재사용
const [uiTexts, setUiTexts] = useState<Record<string, string>>({});

// 한 번 로드한 후 재사용
useEffect(() => {
  if (Object.keys(uiTexts).length === 0) {
    loadTexts();
  }
}, []);
```

### 3. 에러 처리

#### 폴백 시스템 구현

```typescript
const getText = (key: string, fallback?: string) => {
  // 1. 번역된 텍스트 우선
  if (uiTexts[key]) return uiTexts[key];

  // 2. 폴백 텍스트 사용
  if (fallback) return fallback;

  // 3. 키 자체 반환 (디버깅용)
  console.warn(`번역 키를 찾을 수 없음: ${key}`);
  return key;
};
```

#### 로딩 상태 관리

```typescript
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);

const loadTexts = async () => {
  try {
    setLoading(true);
    setError(null);

    const response = await apiClient.post("/multilang/batch", { ... });

    if (response.data.success) {
      setUiTexts(response.data.data);
    } else {
      setError(response.data.message);
    }
  } catch (err) {
    setError('다국어 텍스트 로드 실패');
  } finally {
    setLoading(false);
  }
};
```

## 📝 요약

### 핵심 포인트

1. **useMultiLang 훅**을 사용하여 사용자 언어 설정 관리
2. **배치 API**를 사용하여 여러 키를 한 번에 조회
3. **키 상수**를 정의하여 일관성 유지
4. **폴백 시스템**을 구현하여 번역 실패 시에도 UI 표시
5. **캐싱**을 활용하여 성능 최적화

### 개발 워크플로우

1. 다국어 키 상수 정의
2. 컴포넌트에서 다국어 텍스트 로드
3. UI에 번역된 텍스트 적용
4. 데이터베이스에 번역 데이터 등록
5. 테스트 및 디버깅

### 주의사항

- 키 명명 규칙을 일관되게 유지
- 배치 처리를 사용하여 API 호출 최소화
- 폴백 시스템을 구현하여 사용자 경험 보장
- 성능을 고려한 캐싱 전략 수립

이 가이드를 따라하면 새로운 개발자도 쉽게 다국어 시스템을 이해하고 적용할 수 있을 것입니다.
