Add PDF translation API, utilities, docs, and config
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.
This commit is contained in:
266
ENVIRONMENT_SETUP.md
Normal file
266
ENVIRONMENT_SETUP.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# PDF 翻譯介面 - 環境設置指南
|
||||
|
||||
## 系統需求
|
||||
|
||||
### 基本需求
|
||||
- Node.js 18+
|
||||
- npm 或 yarn
|
||||
- 現代瀏覽器（Chrome、Firefox、Safari、Edge）
|
||||
|
||||
### PDF OCR 功能依賴
|
||||
|
||||
為了完整支援 PDF 掃描文件的 OCR 功能，需要安裝以下系統依賴之一：
|
||||
|
||||
## Windows 系統
|
||||
|
||||
### 方法 1：ImageMagick（推薦）
|
||||
|
||||
1. **下載 ImageMagick**
|
||||
- 訪問：https://imagemagick.org/script/download.php#windows
|
||||
- 下載最新的 Windows 版本（建議選擇 64-bit 版本）
|
||||
- 檔案名類似：`ImageMagick-7.x.x-x-Q16-HDRI-x64-dll.exe`
|
||||
|
||||
2. **安裝步驟**
|
||||
```
|
||||
1. 執行下載的安裝程式
|
||||
2. 選擇「Install development headers and libraries for C and C++」
|
||||
3. 確保勾選「Add application directory to your system path」
|
||||
4. 完成安裝
|
||||
```
|
||||
|
||||
3. **驗證安裝**
|
||||
```bash
|
||||
# 開啟命令提示字元或 PowerShell
|
||||
magick -version
|
||||
```
|
||||
|
||||
### 方法 2：GraphicsMagick
|
||||
|
||||
1. **下載 GraphicsMagick**
|
||||
- 訪問：http://www.graphicsmagick.org/download.html
|
||||
- 選擇 Windows 版本
|
||||
|
||||
2. **安裝後驗證**
|
||||
```bash
|
||||
gm version
|
||||
```
|
||||
|
||||
### 方法 3：Poppler（替代方案）
|
||||
|
||||
1. **下載 Poppler**
|
||||
- 訪問：https://github.com/oschwartz10612/poppler-windows/releases
|
||||
- 下載最新版本
|
||||
|
||||
2. **安裝步驟**
|
||||
```
|
||||
1. 解壓縮到 C:\poppler
|
||||
2. 將 C:\poppler\bin 添加到系統 PATH
|
||||
3. 重新啟動命令提示字元
|
||||
```
|
||||
|
||||
3. **驗證安裝**
|
||||
```bash
|
||||
pdftoppm -h
|
||||
```
|
||||
|
||||
## macOS 系統
|
||||
|
||||
### 使用 Homebrew（推薦）
|
||||
|
||||
```bash
|
||||
# 安裝 Homebrew（如果尚未安裝）
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# 安裝 ImageMagick
|
||||
brew install imagemagick
|
||||
|
||||
# 或者安裝 GraphicsMagick
|
||||
brew install graphicsmagick
|
||||
|
||||
# 或者安裝 Poppler
|
||||
brew install poppler
|
||||
```
|
||||
|
||||
### 驗證安裝
|
||||
```bash
|
||||
# ImageMagick
|
||||
magick -version
|
||||
|
||||
# GraphicsMagick
|
||||
gm version
|
||||
|
||||
# Poppler
|
||||
pdftoppm -h
|
||||
```
|
||||
|
||||
## Linux 系統
|
||||
|
||||
### Ubuntu/Debian
|
||||
|
||||
```bash
|
||||
# ImageMagick
|
||||
sudo apt-get update
|
||||
sudo apt-get install imagemagick
|
||||
|
||||
# 或者 GraphicsMagick
|
||||
sudo apt-get install graphicsmagick
|
||||
|
||||
# 或者 Poppler
|
||||
sudo apt-get install poppler-utils
|
||||
```
|
||||
|
||||
### CentOS/RHEL/Fedora
|
||||
|
||||
```bash
|
||||
# ImageMagick
|
||||
sudo yum install ImageMagick
|
||||
# 或者在較新版本中
|
||||
sudo dnf install ImageMagick
|
||||
|
||||
# GraphicsMagick
|
||||
sudo yum install GraphicsMagick
|
||||
```
|
||||
|
||||
## 應用程式安裝
|
||||
|
||||
### 1. 克隆或下載專案
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd v0-pdf-translation-interface
|
||||
```
|
||||
|
||||
### 2. 安裝依賴
|
||||
|
||||
```bash
|
||||
npm install --legacy-peer-deps
|
||||
```
|
||||
|
||||
### 3. 環境配置
|
||||
|
||||
複製並配置環境變數：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
編輯 `.env` 檔案：
|
||||
|
||||
```env
|
||||
# DeepSeek API Configuration
|
||||
DEEPSEEK_API_KEY=your_deepseek_api_key_here
|
||||
DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||||
DEEPSEEK_MODEL=deepseek-chat
|
||||
|
||||
# OpenAI API Configuration (Backup Option)
|
||||
OPENAI_API_KEY=your_openai_api_key_here
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
|
||||
# AI Provider Selection (deepseek or openai)
|
||||
AI_PROVIDER=deepseek
|
||||
|
||||
# Optional: Maximum file size in bytes (default: 10MB)
|
||||
MAX_FILE_SIZE=10485760
|
||||
```
|
||||
|
||||
### 4. 啟動開發伺服器
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
應用程式將在 http://localhost:3000 啟動
|
||||
|
||||
## 功能測試
|
||||
|
||||
### 測試 PDF 文字提取
|
||||
1. 上傳一個包含文字的 PDF（如文檔、報告）
|
||||
2. 系統應該直接提取文字，不使用 OCR
|
||||
|
||||
### 測試 PDF OCR 功能
|
||||
1. 上傳一個掃描的 PDF（圖片型 PDF）
|
||||
2. 系統應該自動偵測並使用 OCR
|
||||
|
||||
### 測試圖片 OCR 功能
|
||||
1. 上傳 JPG、PNG 等圖片檔案
|
||||
2. 或使用相機拍照功能
|
||||
3. 系統應該使用 OCR 識別文字
|
||||
|
||||
## 常見問題
|
||||
|
||||
### Q: PDF OCR 顯示「需要安裝依賴」錯誤
|
||||
**A:** 請按照上述步驟安裝 ImageMagick、GraphicsMagick 或 Poppler，並重新啟動應用程式。
|
||||
|
||||
### Q: 文字型 PDF 是否需要 OCR？
|
||||
**A:** 不需要。系統會先嘗試直接提取 PDF 中的文字，只有在偵測到掃描型 PDF 時才使用 OCR。
|
||||
|
||||
### Q: 支援哪些檔案格式？
|
||||
**A:**
|
||||
- PDF 檔案（文字型和掃描型）
|
||||
- 圖片檔案：JPG、PNG、GIF、BMP、WebP、TIFF
|
||||
|
||||
### Q: API 金鑰如何取得？
|
||||
**A:**
|
||||
- DeepSeek：https://platform.deepseek.com/
|
||||
- OpenAI：https://platform.openai.com/api-keys
|
||||
|
||||
### Q: 為什麼有費用統計功能？
|
||||
**A:** 幫助你追蹤 AI API 的使用量和費用，支援多個提供商的成本計算。
|
||||
|
||||
## 生產環境部署
|
||||
|
||||
### Vercel 部署
|
||||
|
||||
1. 連接 GitHub 儲存庫到 Vercel
|
||||
2. 設置環境變數
|
||||
3. 部署
|
||||
|
||||
**注意：** Vercel 不支援安裝系統依賴，PDF OCR 功能在 Vercel 上可能受限。建議使用 VPS 或容器化部署。
|
||||
|
||||
### Docker 部署
|
||||
|
||||
創建 `Dockerfile`：
|
||||
|
||||
```dockerfile
|
||||
FROM node:18-alpine
|
||||
|
||||
# 安裝 ImageMagick
|
||||
RUN apk add --no-cache imagemagick
|
||||
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm install --legacy-peer-deps
|
||||
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
EXPOSE 3000
|
||||
CMD ["npm", "start"]
|
||||
```
|
||||
|
||||
### VPS 部署
|
||||
|
||||
1. 安裝 Node.js 和系統依賴
|
||||
2. 克隆專案並安裝依賴
|
||||
3. 配置環境變數
|
||||
4. 使用 PM2 或 systemd 管理程序
|
||||
|
||||
```bash
|
||||
# 使用 PM2
|
||||
npm install -g pm2
|
||||
pm2 start npm --name "pdf-translator" -- start
|
||||
```
|
||||
|
||||
## 系統架構
|
||||
|
||||
- **前端：** Next.js 15 + React 19 + TypeScript + Tailwind CSS
|
||||
- **UI 組件：** shadcn/ui + Radix UI
|
||||
- **PDF 處理：** pdf-lib + pdf-parse
|
||||
- **OCR 引擎：** Tesseract.js
|
||||
- **圖片處理：** Sharp
|
||||
- **AI 集成：** Vercel AI SDK
|
||||
- **PDF 轉圖片：** pdf2pic / pdf-poppler
|
||||
|
||||
## 支援和貢獻
|
||||
|
||||
如有問題或建議，請提交 Issue 或 Pull Request。
|
||||
Reference in New Issue
Block a user