aken1023
39a4788cc4
Introduces core backend and frontend infrastructure for a PDF translation interface. Adds API endpoints for translation, PDF testing, and AI provider testing; implements PDF text extraction, cost tracking, and pricing logic in the lib directory; adds reusable UI components; and provides comprehensive documentation (SDD, environment setup, Claude instructions). Updates Tailwind and global styles, and includes a sample test PDF and configuration files.
17 KiB
17 KiB
軟體設計文件 (Software Design Document)
1. 系統概述
1.1 專案名稱
PDF Translation Interface - PDF 翻譯介面系統
1.2 專案目標
提供一個基於網頁的 PDF 文件翻譯平台，讓使用者能夠上傳 PDF 文件並將其內容翻譯成多種語言。
1.3 系統範圍
- PDF 文件上傳功能（拖拽上傳支援）
- 多層文字擷取處理（pdf-parse → pdf2json 備援）
- OCR 光學字元識別（支援掃描型 PDF）
- AI 驅動的多語言翻譯（DeepSeek + OpenAI 備援）
- 翻譯後 PDF 檔案生成與下載（智慧中文字元處理）
- 翻譯文字檔案下載功能
- 語音播放功能（多語音選擇、速度控制）
- Token 使用量與費用追蹤系統
- 文清楓風格響應式網頁介面（RWD）
2. 系統架構
2.1 技術堆疊
前端技術
- 框架: 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 (SpeechSynthesis)
- 設計風格: 文清楓自然風格（琥珀-綠-青漸變）
- 響應式設計: 完整 RWD 支援（手機/平板/桌面）
後端技術
- 執行環境: Node.js
- API 框架: Next.js API Routes
- PDF 處理: pdf-parse (主要) → pdf2json (備援) → pdfjs-dist (進階)
- OCR 引擎: Tesseract.js (多語言支援)
- PDF 生成: PDFKit + fontkit (Unicode 字體支援)
- AI 整合: Vercel AI SDK
- AI 模型:
- DeepSeek Chat (預設)
- OpenAI GPT-4o-mini (備選)
- 費用追蹤: 本地儲存式 Token 計算與費用統計
- 中文處理: WinAnsi 編碼處理與智慧後備機制
部署與基礎設施
- 部署平台: Vercel
- 版本控制: Git
- 套件管理: npm/pnpm
2.2 系統架構圖
┌─────────────────────────────────────────────────────┐
│ 使用者瀏覽器 │
│ ┌────────────────────────────────────────────┐ │
│ │ React 前端應用程式 │ │
│ │ ├─ PDF 上傳元件 │ │
│ │ ├─ 語言選擇器 │ │
│ │ └─ 翻譯結果顯示 │ │
│ └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
│
│ HTTPS
▼
┌─────────────────────────────────────────────────────┐
│ Next.js 伺服器 │
│ ┌────────────────────────────────────────────┐ │
│ │ API 路由 (/api/translate) │ │
│ │ ├─ PDF 接收與驗證 │ │
│ │ ├─ 文字擷取處理 │ │
│ │ └─ AI 翻譯服務呼叫 │ │
│ └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
│
│ API
▼
┌─────────────────────────────────────────────────────┐
│ AI 翻譯服務 (DeepSeek / OpenAI) │
└─────────────────────────────────────────────────────┘
▲
│
┌─────────────────────────────────────────────────────┐
│ OCR 服務 (Tesseract.js) │
└─────────────────────────────────────────────────────┘
3. 元件設計
3.1 前端元件結構
/components
├── /ui # 基礎 UI 元件
│ ├── button.tsx # 按鈕元件
│ ├── card.tsx # 卡片容器
│ ├── select.tsx # 下拉選單
│ ├── textarea.tsx # 文字輸入區
│ └── alert-dialog.tsx # 警告對話框
│
├── pdf-translator.tsx # 主要應用程式元件
└── theme-provider.tsx # 主題管理元件
3.2 主要元件功能
PDFTranslator 元件
責任：協調整個翻譯工作流程
- 檔案上傳處理
- 語言選擇管理
- API 呼叫協調
- 結果顯示與下載
狀態管理：
- file: File | null // 上傳的 PDF 檔案
- sourceLanguage: string // 來源語言
- targetLanguage: string // 目標語言
- isTranslating: boolean // 翻譯進行狀態
- translatedText: string // 翻譯結果
- translatedPDFBase64: string // 翻譯後的 PDF Base64
- isDragging: boolean // 拖拽狀態
- generatePDF: boolean // 是否生成 PDF
- tokenUsage: any // Token 使用量統計
- cost: any // 單次翻譯費用
- model: any // 使用的 AI 模型資訊
- costSummary: CostSummary // 累積費用統計
// 語音播放相關狀態
- isPlaying: boolean // 語音播放狀態
- isPaused: boolean // 語音暫停狀態
- speechSupported: boolean // 瀏覽器語音支援
- selectedVoice: string // 選擇的語音
- availableVoices: SpeechSynthesisVoice[] // 可用語音列表
- speechRate: number // 播放速度
- speechVolume: number // 播放音量
3.3 API 設計
POST /api/translate
請求格式：
{
file: File, // PDF 檔案
sourceLanguage: string, // 來源語言代碼
targetLanguage: string // 目標語言代碼
}
回應格式：
{
translatedText: string, // 翻譯後的文字
pdfBase64?: string, // 翻譯後的 PDF (Base64)
tokenUsage?: {
prompt: number, // 輸入 Token 數
completion: number, // 輸出 Token 數
total: number, // 總 Token 數
formattedCounts: {
prompt: string,
completion: string,
total: string
}
},
cost?: {
inputCost: number, // 輸入費用
outputCost: number, // 輸出費用
totalCost: number, // 總費用
formattedCost: string, // 格式化費用顯示
currency: string // 貨幣單位
},
model?: {
name: string, // 模型名稱
provider: string, // 提供者
displayName: string // 顯示名稱
},
costSession?: CostSession // 費用追蹤會話
}
錯誤處理：
- 400: 無效的請求參數
- 413: 檔案太大
- 500: 內部伺服器錯誤
4. 資料流程
4.1 翻譯流程
1. 使用者上傳 PDF
└─> 檔案驗證 (類型、大小)
2. 選擇來源與目標語言
└─> 表單驗證
3. 提交翻譯請求
└─> FormData 封裝
└─> POST /api/translate
4. 後端處理
└─> 接收檔案
└─> 多層文字擷取策略
├─> 主要: 使用 pdf-parse 擷取文字
├─> 備援: pdf2json 解析（處理特殊編碼）
└─> 最終: pdfjs-dist 進階處理
└─> 文字預處理與分段
└─> 呼叫 AI 翻譯 API (DeepSeek/OpenAI)
└─> Token 使用量計算與費用追蹤
└─> 整合翻譯結果
5. 生成輸出檔案
└─> 智慧 PDF 生成（處理中文字元編碼）
└─> WinAnsi 編碼限制處理
└─> 中文字元後備描述系統
└─> Unicode 字體支援
6. 顯示結果
└─> 更新 UI（文清楓風格）
└─> Token 使用量與費用顯示
└─> 累積費用統計更新
└─> 語音播放功能啟用
└─> 提供下載選項
├─> 下載翻譯後 PDF
└─> 下載純文字檔案
└─> 語音播放控制
├─> 播放/暫停/停止
├─> 語音選擇
└─> 速度調整
4.2 PDF 處理流程
4.2.1 文字型 PDF 處理（多層備援）
輸入: PDF 檔案
│
├─> 第一層: pdf-parse 解析
│ ├─> 成功: 擷取文字內容
│ └─> 失敗: 進入第二層
│
├─> 第二層: pdf2json 解析
│ ├─> 成功: 解碼 URI 編碼文字
│ └─> 失敗: 進入第三層
│
├─> 第三層: pdfjs-dist 解析
│ ├─> 成功: 進階文字擷取
│ └─> 失敗: 回報錯誤
│
├─> 文字長度與品質檢查
├─> 保留段落結構
└─> 傳送至翻譯 API
4.2.2 掃描型 PDF 處理 (OCR)
輸入: 掃描的 PDF 檔案
│
├─> 將 PDF 轉換為圖片
├─> 每頁進行 OCR 識別
│ ├─> 語言偵測
│ ├─> 文字區域識別
│ └─> 文字擷取
├─> 合併所有頁面文字
├─> 文字校正與優化
└─> 傳送至翻譯 API
4.3 翻譯後 PDF 生成流程（智慧中文處理）
翻譯完成的文字
│
├─> 中文字元檢測
├─> 智慧 PDF 生成策略
│ ├─> 中文內容: 使用後備描述系統
│ │ ├─> WinAnsi 編碼限制處理
│ │ ├─> 生成內容描述
│ │ └─> 添加重要提示
│ └─> 非中文: 標準 PDF 生成
│
├─> 使用 PDFKit + fontkit
│ ├─> Unicode 字體支援
│ ├─> 標準字體後備
│ └─> 錯誤處理機制
│
├─> 頁面佈局與格式
│ ├─> 標題與語言資訊
│ ├─> 重要提示區域
│ └─> 內容區域分頁
│
└─> Base64 編碼輸出
5. 介面設計
5.1 使用者介面流程
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ 檔案上傳 │ --> │ 語言選擇 │ --> │ 開始翻譯 │
└────────────────┘ └────────────────┘ └────────────────┘
│
▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ 下載結果 │ <-- │ 顯示翻譯 │ <-- │ 處理中... │
└────────────────┘ └────────────────┘ └────────────────┘
5.2 響應式設計（文清楓風格）
-
桌面版 (xl:grid-cols-2)：雙欄佈局 (上傳區 | 結果區)
- 寬敞間距 (p-8, gap-8)
- 完整文字與圖標顯示
- 琥珀-綠-青漸變背景
-
平板版 (lg)：單欄佈局，適中間距
- 中等間距 (p-6, gap-6)
- 保持主要功能文字
- 優化觸控目標大小
-
手機版 (sm)：縱向堆疊，緊湊佈局
- 緊湊間距 (p-4, gap-4)
- 圖標化界面 (隱藏部分文字)
- 按鈕與控制項優化
- 垂直排列下載按鈕
5.3 文清楓設計特色
- 自然色彩: 琥珀(amber) → 綠(green) → 青(teal)漸變
- 裝飾元素: 半透明背景圓圈、表情符號點綴
- 卡片設計: 毛玻璃效果 (backdrop-blur-sm)
- 漸變邊框: 各功能區域協調色彩變化
6. 安全性考量
6.1 輸入驗證
- 檔案類型限制 (僅 PDF)
- 檔案大小限制
- 語言代碼驗證
- XSS 防護
6.2 API 安全
- API 金鑰環境變數管理
- Rate limiting (建議實作)
- CORS 配置
- HTTPS 加密傳輸
6.3 隱私保護
- 不儲存使用者檔案
- 不記錄翻譯內容
- 僅記錄匿名使用統計
7. 核心功能實作細節
7.1 PDF 文字擷取實作
// 使用 pdf-parse 套件
import pdf from 'pdf-parse'
async function extractTextFromPDF(buffer: Buffer) {
const data = await pdf(buffer)
return {
text: data.text,
numPages: data.numpages,
info: data.info
}
}
7.2 OCR 文字識別實作
// 使用 Tesseract.js
import Tesseract from 'tesseract.js'
async function performOCR(imageBuffer: Buffer, language: string) {
const result = await Tesseract.recognize(
imageBuffer,
language,
{
logger: m => console.log(m)
}
)
return result.data.text
}
7.3 翻譯後 PDF 生成實作
// 使用 PDFKit
import PDFDocument from 'pdfkit'
function generateTranslatedPDF(translatedText: string, metadata: any) {
const doc = new PDFDocument()
// 設定字體支援多語言
doc.font('fonts/NotoSansCJK.ttf')
// 加入翻譯文字
doc.text(translatedText, {
align: 'left',
lineGap: 5
})
return doc
}
8. 效能優化
8.1 前端優化
- 元件懶加載
- 圖片優化
- CSS 最小化
- Tree shaking
- 大檔案分片上傳
8.2 後端優化
- API 回應快取
- 串流處理大檔案
- 非同步處理
- 批次處理多頁 PDF
- OCR 結果快取
9. 支援的語言
系統支援以下 16 種語言的雙向翻譯：
- 自動偵測 (auto) - 僅限來源語言
- 繁體中文 (zh-TW) 🎤
- 簡體中文 (zh-CN) 🎤
- 英語 (en) 🎤
- 日語 (ja) 🎤
- 韓語 (ko) 🎤
- 西班牙語 (es) 🎤
- 法語 (fr) 🎤
- 德語 (de) 🎤
- 義大利語 (it) 🎤
- 葡萄牙語 (pt) 🎤
- 俄語 (ru) 🎤
- 阿拉伯語 (ar) 🎤
- 印地語 (hi) 🎤
- 泰語 (th) 🎤
- 越南語 (vi) 🎤
🎤 = 支援語音播放功能（根據瀏覽器可用語音）
9.1 語音播放支援
- Web Speech API: 瀏覽器原生語音合成
- 多語音選擇: 根據目標語言自動篩選
- 語音控制: 播放、暫停、停止、速度調整
- 語音品質: 依瀏覽器與系統語音包而定
10. 部署架構
10.1 Vercel 部署配置
{
buildCommand: "npm run build",
outputDirectory: ".next",
installCommand: "npm install",
framework: "nextjs"
}
10.2 環境變數
# AI 服務提供者選擇
AI_PROVIDER=deepseek # 或 openai
# DeepSeek 配置
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_MODEL=deepseek-chat
# OpenAI 配置（備選）
OPENAI_API_KEY=sk-xxxxxxxxxxxx
OPENAI_MODEL=gpt-4o-mini
# 應用程式設定
NODE_ENV=production
MAX_FILE_SIZE=10485760 # 10MB
# 費用追蹤設定
ENABLE_COST_TRACKING=true
DEFAULT_CURRENCY=USD
# PDF 處理設定
PDF_PROCESSING_TIMEOUT=30000 # 30秒
OCR_LANGUAGE_DEFAULT=chi_tra+eng
11. 未來擴展計畫
11.1 功能增強
- 批次檔案處理
- 保留 PDF 格式輸出
- 翻譯歷史記錄
- 使用者帳號系統
- 自訂詞彙表
11.2 技術改進
- [✓] 實作多層 PDF 解析（pdf-parse → pdf2json → pdfjs-dist）
- [✓] 整合 OCR 功能（使用 Tesseract.js）
- [✓] 智慧 PDF 生成（PDFKit + 中文字元處理）
- [✓] 整合多個 AI 模型（DeepSeek + OpenAI）
- [✓] Token 使用量與費用追蹤系統
- [✓] 語音播放功能（多語音、速度控制）
- [✓] 文清楓風格響應式設計
- [✓] 拖拽上傳功能
- [✓] 累積費用統計與重置
- 添加進度條顯示
- 實作檔案分塊處理
- 添加翻譯品質評分
- 添加更多 OCR 語言支援
11.3 效能優化
- 實作 Redis 快取
- CDN 整合
- 工作佇列系統
- 資料庫整合
12. 測試策略
12.1 單元測試
- 元件渲染測試
- 函數邏輯測試
- API 端點測試
- PDF 處理測試
- 文字型 PDF 擷取
- OCR 識別測試
- PDF 生成測試
12.2 整合測試
- 檔案上傳流程
- 翻譯流程測試
- 錯誤處理測試
12.3 端對端測試
- 完整使用者流程
- 跨瀏覽器測試
- 響應式設計測試
13. 維護與監控
13.1 日誌記錄
- 錯誤日誌
- 效能指標
- 使用統計
13.2 監控指標
- API 回應時間
- 翻譯成功率
- 系統可用性
- 使用者活躍度
14. 文件與支援
14.1 開發文件
- API 文件
- 元件文件
- 部署指南
14.2 使用者文件
- 使用教學
- 常見問題
- 疑難排解指南