pdf-translation-interface/ENVIRONMENT_SETUP.md

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. 驗證安裝

   # 開啟命令提示字元或 PowerShell
   magick -version
   

方法 2：GraphicsMagick

1. 下載 GraphicsMagick

   • 訪問：http://www.graphicsmagick.org/download.html
   • 選擇 Windows 版本

2. 安裝後驗證

   gm version
   

方法 3：Poppler（替代方案）

1. 下載 Poppler

   • 訪問：https://github.com/oschwartz10612/poppler-windows/releases
   • 下載最新版本

2. 安裝步驟

   1. 解壓縮到 C:\poppler
   2. 將 C:\poppler\bin 添加到系統 PATH
   3. 重新啟動命令提示字元
   

3. 驗證安裝

   pdftoppm -h
   

macOS 系統

使用 Homebrew（推薦）

# 安裝 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

驗證安裝

# ImageMagick
magick -version

# GraphicsMagick  
gm version

# Poppler
pdftoppm -h

Linux 系統

Ubuntu/Debian

# 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

# ImageMagick
sudo yum install ImageMagick
# 或者在較新版本中
sudo dnf install ImageMagick

# GraphicsMagick
sudo yum install GraphicsMagick

應用程式安裝

1. 克隆或下載專案

git clone <repository-url>
cd v0-pdf-translation-interface

2. 安裝依賴

npm install --legacy-peer-deps

3. 環境配置

複製並配置環境變數：

cp .env.example .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. 啟動開發伺服器

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：

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 管理程序

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