Translation API

Babelfish translation service deployed as Vercel serverless functions. Provides language detection and translation services with Google Spreadsheet caching.

Endpoints

GET /api/detect-language

Detect the language of a text query.

Parameters:

• query (string, required) - Text to detect language for

Example:

curl "https://your-deployment.vercel.app/api/detect-language?query=hello"

Response:

{
  "ok": 1,
  "language": "en",
  "confidence": 1,
  "alternate": null,
  "name": "English"
}

POST /api/translate

Translate text from one language to another with caching.

Parameters:

• query (string, required) - Text to translate
• langFrom (string, required) - Source language code (e.g., "en", "zh-CN")
• langTo (string, required) - Target language code (e.g., "en", "zh-CN")
• secret (string, required) - Shared secret for authentication
• langConfidence (number, optional) - Language detection confidence
• langAlternate (string, optional) - Alternate language suggestion
• langName (string, optional) - Human-readable language name

Example:

curl -X POST https://your-deployment.vercel.app/api/translate \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=hello&langFrom=en&langTo=zh-CN&secret=your_secret"

Response:

{
  "ok": 1,
  "query": "hello",
  "langFrom": "en",
  "langTo": "zh-CN",
  "translated": "你好",
  "sensitive": false,
  "saved": true,
  "source": "google"
}

Setup

1. Install Dependencies

npm install

2. Configure Environment Variables

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Required variables:

• GOOGLE_TRANSLATE_API_KEY - Your Google Translate API key
• SHARED_SECRET - Secret key for authenticating translation requests

Optional variables (for caching):

• GOOGLE_SPREADSHEET_ID - Google Sheet ID for caching translations
• GOOGLE_SERVICE_ACCOUNT_KEY - Service account credentials as JSON string

3. Local Development

Start the local development server:

npm run dev

The API will be available at http://localhost:3002

Test language detection:

curl "http://localhost:3002/api/detect-language?query=hello"

Test translation:

curl -X POST http://localhost:3002/api/translate \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=hello&langFrom=en&langTo=zh-CN&secret=your_secret"

4. Deploy to Vercel

npm run deploy

Or connect your GitHub repository to Vercel for automatic deployments.

Environment Variables on Vercel

After deploying, configure the following environment variables in your Vercel project settings:

1. Go to your project on Vercel
2. Navigate to Settings → Environment Variables
3. Add each variable from .env.example

Architecture

Caching Strategy

Translations are cached in a Google Spreadsheet with three priority levels:

1. Sensitive terms (highest priority) - Special terms with manual translations
2. Override translations - Manually corrected translations
3. Cached Google translations - Previously fetched translations

If no cache exists, the API fetches from Google Translate and saves to the spreadsheet.

Authentication

The /api/translate endpoint requires a shared secret passed as the secret parameter. This prevents unauthorized usage and API quota consumption.

Language Detection

The /api/detect-language endpoint does not require authentication and can be called freely. It returns the detected language code, confidence level, and human-readable language name.

Migration from Original Babelfish

This serverless version replaces the original Node.js HTTP/HTTPS server with Vercel functions. Key differences:

• No Socket.io - Real-time features removed (not suitable for serverless)
• On-demand caching - Spreadsheet loaded per request with 5-minute cache
• Simplified authentication - Uses shared secret only (no service account validation)
• Removed endpoints - /query, /submit-images, /images not included

Development

Project Structure

translate-api/
├── api/              # Serverless function endpoints
├── lib/              # Shared utilities and services
├── package.json      # Dependencies and scripts
├── vercel.json       # Vercel deployment config
└── local-server.js   # Local development server

Adding New Endpoints

1. Create a new file in /api/ (e.g., /api/new-endpoint.js)
2. Export a handler function wrapped with allowCors()
3. Add route to local-server.js for local testing

License

Part of the Firewall Cafe project.