# 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。