更新 README.md

2025-10-15 23:46:54 +08:00
parent 39a4788cc4
commit a77c7f6e98
1 changed files with 331 additions and 18 deletions
--- a/README.md
+++ b/README.md
@@ -1,30 +1,343 @@
-# PDF translation interface
+# 文清楓 PDF 翻譯介面 🍃
-*Automatically synced with your [v0.app](https://v0.app) deployments*
+一個基於 Next.js 15 和 AI 驅動的智慧 PDF 翻譯平台，採用文清楓風格設計，提供優雅的多語言翻譯體驗。
-[![Deployed on Vercel](https://img.shields.io/badge/Deployed%20on-Vercel-black?style=for-the-badge&logo=vercel)](https://vercel.com/akens-projects-fce998a9/v0-pdf-translation-interface)
+[![Next.js](https://img.shields.io/badge/Next.js-15.2.4-black?style=for-the-badge&logo=next.js)](https://nextjs.org/)
-[![Built with v0](https://img.shields.io/badge/Built%20with-v0.app-black?style=for-the-badge)](https://v0.app/chat/projects/LiqnDOZ2CwR)
+[![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/)
-## Overview
+## ✨ 主要功能
-This repository will stay in sync with your deployed chats on [v0.app](https://v0.app).
+- 🔄 **智慧 PDF 處理**: 多層文字擷取策略 (pdf-parse → pdf2json 備援)
-Any changes you make to your deployed app will be automatically pushed to this repository from [v0.app](https://v0.app).
+- 🌐 **16 種語言支援**: 包含自動偵測和雙向翻譯
 - 🎨 **文清楓風格**: 琥珀-綠-青漸變的自然優雅設計
 - 📱 **完整響應式**: 手機/平板/桌面完美適配 (RWD)
 - 🔊 **語音播放**: Web Speech API 多語音朗讀
 - 💰 **費用追蹤**: 即時 Token 使用量與成本統計
 - 📥 **拖拽上傳**: 便捷的檔案上傳體驗
 - 📄 **智慧 PDF 生成**: 處理中文字元編碼問題
-## Deployment
+## 🚀 快速開始
-Your project is live at:
+### 環境需求
-**[https://vercel.com/akens-projects-fce998a9/v0-pdf-translation-interface](https://vercel.com/akens-projects-fce998a9/v0-pdf-translation-interface)**
+- Node.js 18.0.0 或更高版本
 - npm 或 yarn 套件管理器
-## Build your app
+### 1. 克隆專案
-Continue building your app on:
+```bash
 git clone https://github.com/your-username/v0-pdf-translation-interface.git
 cd v0-pdf-translation-interface
 ```
-**[https://v0.app/chat/projects/LiqnDOZ2CwR](https://v0.app/chat/projects/LiqnDOZ2CwR)**
+### 2. 安裝依賴
-## How It Works
+```bash
 npm install
 # 或者
 yarn install
 ```
-1. Create and modify your project using [v0.app](https://v0.app)
+### 3. 建立環境變數檔案
-2. Deploy your chats from the v0 interface
+
-3. Changes are automatically pushed to this repository
+在專案根目錄建立 `.env.local` 檔案：
-4. Vercel deploys the latest version from this repository
+
 ```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 模型服務