343 lines
9.6 KiB
Markdown
343 lines
9.6 KiB
Markdown
# 文清楓 PDF 翻譯介面 🍃
|
||
|
||
一個基於 Next.js 15 和 AI 驅動的智慧 PDF 翻譯平台，採用文清楓風格設計，提供優雅的多語言翻譯體驗。
|
||
|
||
[](https://nextjs.org/)
|
||
[](https://reactjs.org/)
|
||
[](https://www.typescriptlang.org/)
|
||
[](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 模型服務 |