aken1023/pdf-translation-interface
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6d51358cfef24403365a4657f8bb636c85e9fa54
pdf-translation-interface/CLAUDE.md
aken1023 39a4788cc4 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

2.8 KiB
Raw Blame History

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

# 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