# Malaysian Language Translation API

말레이시아어(Bahasa Melayu)와 영어 간의 자연스러운 번역을 제공하는 REST API 서비스입니다.

## 주요 기능

- 말레이시아어 ↔ 영어 양방향 번역
- Helsinki-NLP의 OPUS-MT 신경망 기계 번역 모델 사용
- FastAPI 기반 고성능 REST API
- Docker를 통한 간편한 배포
- 자동 API 문서화 (Swagger UI)

## 빠른 시작

### 1. 로컬 환경 설정

```bash
# Python 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

# 환경변수 설정 (선택사항)
cp .env.example .env

# 서버 실행
python run.py
```

서버가 실행되면 http://localhost:8000 에서 API에 접근할 수 있습니다.

### 2. Docker로 실행

```bash
# Docker Compose로 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f
```

## API 사용법

### 번역 요청

```bash
curl -X POST "http://localhost:8000/api/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Selamat pagi, apa khabar?",
    "source_lang": "ms",
    "target_lang": "en"
  }'
```

응답:
```json
{
  "original_text": "Selamat pagi, apa khabar?",
  "translated_text": "Good morning, how are you?",
  "source_lang": "ms",
  "target_lang": "en",
  "model_used": "Helsinki-NLP/opus-mt-ms-en"
}
```

### 지원 언어 확인

```bash
curl http://localhost:8000/api/supported-languages
```

### 헬스체크

```bash
curl http://localhost:8000/health
```

## API 문서

서버 실행 후 다음 URL에서 자동 생성된 API 문서를 확인할 수 있습니다:

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 지원 언어

- **ms**: 말레이시아어 (Bahasa Melayu)
- **en**: 영어 (English)

## 프로젝트 구조

```
site13/
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI 애플리케이션 및 엔드포인트
│   ├── models.py        # Pydantic 데이터 모델
│   ├── translator.py    # 번역 서비스 로직
│   └── config.py        # 설정 관리
├── models/              # 다운로드된 번역 모델 캐시 (자동 생성)
├── requirements.txt     # Python 의존성
├── run.py              # 서버 실행 스크립트
├── Dockerfile          # Docker 이미지 빌드 설정
├── docker-compose.yml  # Docker Compose 설정
└── README.md           # 프로젝트 문서
```

## 환경 변수

`.env` 파일에서 다음 설정을 변경할 수 있습니다:

- `API_HOST`: API 서버 호스트 (기본값: 0.0.0.0)
- `API_PORT`: API 서버 포트 (기본값: 8000)
- `MODEL_CACHE_DIR`: 모델 캐시 디렉토리 (기본값: ./models)
- `MAX_LENGTH`: 최대 번역 길이 (기본값: 512)
- `ALLOWED_ORIGINS`: CORS 허용 오리진 (기본값: *)

## 성능 최적화

- 첫 실행 시 모델을 다운로드하므로 시간이 걸릴 수 있습니다
- 모델은 `models/` 디렉토리에 캐시되어 재사용됩니다
- GPU가 있는 경우 자동으로 감지하여 사용합니다
- Docker volume을 사용하여 모델을 영구 저장합니다

## 개발

```bash
# 개발 모드로 실행 (자동 재시작)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## 라이선스

이 프로젝트는 Helsinki-NLP의 OPUS-MT 모델을 사용합니다.