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.
266 lines
5.3 KiB
Markdown
266 lines
5.3 KiB
Markdown
# 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。 |