# 文清楓 PDF 翻譯介面 🍃

一個基於 Next.js 15 和 AI 驅動的智慧 PDF 翻譯平台，採用文清楓風格設計，提供優雅的多語言翻譯體驗。

[![Next.js](https://img.shields.io/badge/Next.js-15.2.4-black?style=for-the-badge&logo=next.js)](https://nextjs.org/)
[![React](https://img.shields.io/badge/React-19.0.0-blue?style=for-the-badge&logo=react)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind%20CSS-v4.1.9-38B2AC?style=for-the-badge&logo=tailwind-css)](https://tailwindcss.com/)

## ✨ 主要功能

- 🔄 **智慧 PDF 處理**: 多層文字擷取策略 (pdf-parse → pdf2json 備援)
- 🌐 **16 種語言支援**: 包含自動偵測和雙向翻譯
- 🎨 **文清楓風格**: 琥珀-綠-青漸變的自然優雅設計
- 📱 **完整響應式**: 手機/平板/桌面完美適配 (RWD)
- 🔊 **語音播放**: Web Speech API 多語音朗讀
- 💰 **費用追蹤**: 即時 Token 使用量與成本統計
- 📥 **拖拽上傳**: 便捷的檔案上傳體驗
- 📄 **智慧 PDF 生成**: 處理中文字元編碼問題

## 🚀 快速開始

### 環境需求

- Node.js 18.0.0 或更高版本
- npm 或 yarn 套件管理器

### 1. 克隆專案

```bash
git clone https://github.com/your-username/v0-pdf-translation-interface.git
cd v0-pdf-translation-interface
```

### 2. 安裝依賴

```bash
npm install
# 或者
yarn install
```

### 3. 建立環境變數檔案

在專案根目錄建立 `.env.local` 檔案：

```bash
# 複製環境變數範本
cp .env.example .env.local
```

在 `.env.local` 中設定以下環境變數：

```env
# ===========================================
# AI 服務提供者設定 (必填)
# ===========================================

# 選擇 AI 提供者: 'deepseek' 或 'openai'
AI_PROVIDER=deepseek

# ===========================================
# DeepSeek 設定 (推薦 - 成本較低)
# ===========================================
# 註冊網址: https://platform.deepseek.com/
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_MODEL=deepseek-chat

# ===========================================
# OpenAI 設定 (備選)
# ===========================================
# 註冊網址: https://platform.openai.com/
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_MODEL=gpt-4o-mini

# ===========================================
# 應用程式設定 (可選)
# ===========================================

# 檔案大小限制 (位元組)
MAX_FILE_SIZE=10485760

# 費用追蹤設定
ENABLE_COST_TRACKING=true
DEFAULT_CURRENCY=USD

# PDF 處理設定
PDF_PROCESSING_TIMEOUT=30000
OCR_LANGUAGE_DEFAULT=chi_tra+eng

# 開發環境設定
NODE_ENV=development
```

### 4. AI API 金鑰設定指南

#### 選項 A: DeepSeek (推薦 - 經濟實惠)

1. 前往 [DeepSeek Platform](https://platform.deepseek.com/)
2. 註冊並登入帳號
3. 前往 API Keys 頁面
4. 創建新的 API 金鑰
5. 複製金鑰到 `DEEPSEEK_API_KEY`

**優勢:**
- 💰 成本較低 (約為 OpenAI 的 1/10)
- 🇨🇳 對中文支援優秀
- ⚡ 回應速度快

#### 選項 B: OpenAI (備選)

1. 前往 [OpenAI Platform](https://platform.openai.com/)
2. 註冊並登入帳號
3. 前往 API Keys 頁面
4. 創建新的 API 金鑰
5. 複製金鑰到 `OPENAI_API_KEY`

**優勢:**
- 🌍 多語言品質穩定
- 🔬 先進的語言模型
- 📚 豐富的文檔支援

### 5. 啟動開發伺服器

```bash
npm run dev
# 或者
yarn dev
```

開啟瀏覽器訪問 [http://localhost:3000](http://localhost:3000)

## 📋 支援的語言

系統支援以下 16 種語言的雙向翻譯：

| 語言 | 代碼 | 語音支援 |
|------|------|----------|
| 自動偵測 | auto | - |
| 繁體中文 | zh-TW | ✅ |
| 簡體中文 | zh-CN | ✅ |
| English | en | ✅ |
| 日本語 | ja | ✅ |
| 한국어 | ko | ✅ |
| Español | es | ✅ |
| Français | fr | ✅ |
| Deutsch | de | ✅ |
| Italiano | it | ✅ |
| Português | pt | ✅ |
| Русский | ru | ✅ |
| العربية | ar | ✅ |
| हिन्दी | hi | ✅ |
| ไทย | th | ✅ |
| Tiếng Việt | vi | ✅ |

## 🛠️ 技術架構

### 前端技術
- **框架**: Next.js 15.2.4 (App Router)
- **UI 庫**: React 19.0.0
- **程式語言**: TypeScript 5
- **樣式系統**: Tailwind CSS v4.1.9
- **元件庫**: shadcn/ui + Radix UI
- **圖標**: Lucide React
- **語音合成**: Web Speech API

### 後端技術
- **執行環境**: Node.js
- **API 框架**: Next.js API Routes
- **PDF 處理**: pdf-parse, pdf2json (多層備援)
- **PDF 生成**: PDFKit + fontkit (Unicode 支援)
- **AI 整合**: Vercel AI SDK
- **AI 模型**: DeepSeek Chat / OpenAI GPT-4o-mini

### 部署平台
- **主要**: Vercel
- **替代**: Any Node.js hosting platform

## 📁 專案結構

```
├── app/                    # Next.js 15 App Router
│   ├── api/               # API 路由
│   │   └── translate/     # 翻譯 API 端點
│   ├── globals.css        # 全域樣式
│   ├── layout.tsx         # 根佈局
│   └── page.tsx           # 首頁
├── components/            # React 元件
│   ├── ui/               # 基礎 UI 元件 (shadcn/ui)
│   └── pdf-translator.tsx # 主要應用程式元件
├── lib/                  # 工具函式與邏輯
│   ├── utils.ts          # 通用工具函式
│   ├── pdf-processor.ts  # PDF 處理核心邏輯
│   ├── pdf-to-image.ts   # PDF 轉圖片功能
│   └── cost-tracker.ts   # 費用追蹤系統
├── public/               # 靜態檔案
├── SDD.md               # 軟體設計文件
├── TDD.md               # 技術設計文件
└── README.md            # 專案說明文件
```

## 🎨 文清楓設計特色

### 色彩系統
- **主色調**: 琥珀(amber) → 綠(green) → 青(teal) 漸變
- **背景**: 自然溫暖色調，半透明層次
- **裝飾**: 毛玻璃效果與浮動圓圈元素

### 響應式設計
- **桌面版** (xl): 雙欄佈局，寬敞間距
- **平板版** (lg): 單欄佈局，適中間距  
- **手機版** (sm): 縱向堆疊，緊湊佈局

## 💰 費用說明

### DeepSeek 費用 (推薦)
- **輸入**: $0.00014 / 1K tokens
- **輸出**: $0.00028 / 1K tokens
- **平均翻譯成本**: $0.002 - $0.01 per page

### OpenAI 費用
- **GPT-4o-mini 輸入**: $0.00015 / 1K tokens
- **GPT-4o-mini 輸出**: $0.0006 / 1K tokens
- **平均翻譯成本**: $0.01 - $0.05 per page

*系統會即時追蹤並顯示每次翻譯的 Token 使用量與費用*

## 🔧 開發指令

```bash
# 開發模式
npm run dev

# 建置專案
npm run build

# 啟動生產版本
npm start

# 程式碼檢查
npm run lint

# 型別檢查
npm run type-check
```

## 📋 功能使用指南

### 1. 基本翻譯流程
1. 📁 上傳 PDF 檔案 (支援拖拽)
2. 🌐 選擇來源語言 (可設為自動偵測)
3. 🎯 選擇目標語言
4. ⚙️ 選擇是否生成翻譯後的 PDF
5. ▶️ 點擊「開始翻譯」
6. 📄 查看翻譯結果與費用統計

### 2. 語音播放功能
1. 🔊 翻譯完成後，點擊語音播放區域
2. 🎤 選擇適合的語音 (系統自動推薦)
3. ⚡ 調整播放速度 (0.5x - 2.0x)
4. ▶️ 播放 / ⏸️ 暫停 / ⏹️ 停止控制

### 3. 檔案下載
- 📄 **文字檔**: 下載純文字版翻譯結果 (.txt)
- 📋 **PDF 檔**: 下載翻譯後的 PDF 檔案

### 4. 費用追蹤
- 💰 查看單次翻譯的 Token 使用量與費用
- 📊 查看累積使用統計
- 🔄 重置費用記錄 (本地儲存)

## ⚠️ 注意事項

### 檔案限制
- **檔案類型**: 僅支援 PDF 格式
- **檔案大小**: 最大 10MB
- **內容要求**: 需含有可提取的文字內容

### PDF 處理說明
- **文字型 PDF**: 直接提取文字，處理速度快
- **掃描型 PDF**: 需要 OCR 識別，處理時間較長
- **加密 PDF**: 目前不支援，請先解除保護

### 中文 PDF 輸出
由於 PDF 字體編碼限制，中文內容會：
- 🔤 在 PDF 中顯示為英文描述
- 📄 完整中文翻譯可下載文字檔案
- 💡 PDF 檔案會包含重要提示說明

## 🐛 疑難排解

### 常見問題

**Q: 翻譯按鈕無法點擊？**
A: 請確認已上傳 PDF 檔案且選擇了目標語言

**Q: PDF 顯示「無法讀取內容」？**
A: 可能是掃描版 PDF 或加密檔案，請嘗試其他 PDF 檔案

**Q: API 金鑰錯誤？**
A: 請檢查 `.env.local` 檔案中的 API 金鑰是否正確設定

**Q: 語音播放沒有聲音？**
A: 請檢查瀏覽器是否支援語音合成，並確認音量設定

**Q: 費用統計顯示異常？**
A: 費用資料儲存在瀏覽器本地，清除瀏覽器資料會重置記錄

### 技術支援

如果遇到問題，請：
1. 查看瀏覽器開發者工具的 Console 錯誤訊息
2. 確認網路連線狀況
3. 檢查 API 金鑰額度
4. 提交 Issue 到 GitHub Repository

## 📄 文檔

- 📋 [軟體設計文件 (SDD)](./SDD.md)
- 🔧 [技術設計文件 (TDD)](./TDD.md)

## 🤝 貢獻指南

歡迎提交 Pull Request 或 Issue！

1. Fork 這個專案
2. 創建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交變更 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 開啟 Pull Request

## 📄 授權

本專案採用 MIT 授權 - 詳見 [LICENSE](LICENSE) 檔案

## 🙏 致謝

- [Next.js](https://nextjs.org/) - React 框架
- [Tailwind CSS](https://tailwindcss.com/) - CSS 框架
- [shadcn/ui](https://ui.shadcn.com/) - UI 元件庫
- [Vercel AI SDK](https://sdk.vercel.ai/) - AI 整合
- [DeepSeek](https://platform.deepseek.com/) - AI 模型服務