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.
2025-10-15 23:34:44 +08:00
parent c899702d51
commit 39a4788cc4
21 changed files with 11041 additions and 251 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a PDF Translation Interface built with Next.js 15 and React 19. The application allows users to upload PDF files and translate them into multiple languages using OpenAI's GPT-4o-mini model.
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Start production server
+npm run start
+
+# Run linter
+npm run lint
+```
+
+## Architecture
+
+### Tech Stack
+- **Framework**: Next.js 15.2.4 with App Router
+- **UI**: React 19 with TypeScript
+- **Styling**: Tailwind CSS v4 with CSS variables for theming
+- **Components**: shadcn/ui with Radix UI primitives
+- **AI Integration**: Vercel AI SDK with OpenAI
+
+### Key Architectural Decisions
+
+1. **Component Structure**: Main functionality is centralized in `components/pdf-translator.tsx`. UI components follow shadcn/ui patterns using Radix UI primitives with Class Variance Authority for variants.
+
+2. **API Design**: Translation endpoint at `/api/translate/route.ts` handles PDF processing and AI translation. Currently uses simulated PDF text extraction - production implementation requires a proper PDF parsing library.
+
+3. **Styling System**: Uses modern Tailwind CSS v4 with OKLCH color space. Theme variables are defined as CSS custom properties in `app/globals.css`.
+
+4. **State Management**: Simple React hooks for local state. No global state management needed for current functionality.
+
+## Important Implementation Notes
+
+### PDF Processing
+The current implementation simulates PDF text extraction. For production:
+- Install a PDF parsing library (e.g., `pdf-parse` or `pdfjs-dist`)
+- Update `/app/api/translate/route.ts` to properly extract text from uploaded PDFs
+- Handle various PDF formats and encodings
+
+### Translation API
+- Uses OpenAI GPT-4o-mini model via Vercel AI SDK
+- API key must be set as `OPENAI_API_KEY` environment variable
+- Supports 14 languages including Traditional Chinese, English, Japanese, Korean
+
+### Build Configuration
+- TypeScript and ESLint errors are ignored during builds (see `next.config.mjs`)
+- Images are unoptimized for faster builds
+- Configured for Vercel deployment
+
+## Testing
+No testing framework is currently configured. When adding tests:
+- Use Jest with React Testing Library for unit tests
+- Consider Playwright for E2E tests
+- Test the translation API endpoint thoroughly
+- Mock the OpenAI API calls in tests
+
+## Environment Variables
+Required for production:
+```
+OPENAI_API_KEY=your_openai_api_key
+```
+
+## Known Limitations
+1. PDF text extraction is simulated - needs proper implementation
+2. No file size validation or limits
+3. No progress indication for large files
+4. No caching of translations
+5. No error recovery for failed API calls