Using LocaleLens in Production

Best practices for deploying LocaleLens in production applications

This guide covers the essential patterns for using LocaleLens safely and efficiently in production. The key principles are: keep API keys server-side, cache aggressively, and monitor usage.

This guide is intended for applications running in production environments (Next.js, SSR, backend-backed SPAs). If you're experimenting locally, see the framework guides instead.

Backend Proxy Pattern

Never expose API keys in client-side code

API keys in browser code can be extracted and abused. Always fetch translations through your own backend.

Create a backend endpoint that proxies requests to LocaleLens. Your API key stays on the server, and you control caching and access.

Next.js (App Router)

Create app/api/translations/[locale]/route.ts:

import { NextResponse } from 'next/server'

const API_URL = 'https://localelens.ai/api/v1'
const PROJECT_ID = process.env.LOCALELENS_PROJECT_ID!
const API_KEY = process.env.LOCALELENS_API_KEY!

export async function GET(
  request: Request,
  { params }: { params: { locale: string } }
) {
  const response = await fetch(
    `${API_URL}/projects/${PROJECT_ID}/translations/${params.locale}`,
    {
      headers: { Authorization: `Bearer ${API_KEY}` },
      next: { revalidate: 3600 }, // Cache for 1 hour
    }
  )

  if (!response.ok) {
    return NextResponse.json(
      { error: 'Failed to fetch translations' },
      { status: response.status }
    )
  }

  const data = await response.json()

  return NextResponse.json(data, {
    headers: {
      'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
    },
  })
}

Vite + Express

Create an Express endpoint:

import express from 'express'

const app = express()

const API_URL = 'https://localelens.ai/api/v1'
const PROJECT_ID = process.env.LOCALELENS_PROJECT_ID!
const API_KEY = process.env.LOCALELENS_API_KEY!

// Simple in-memory cache
const cache = new Map<string, { data: unknown; expires: number }>()
const CACHE_TTL = 3600 * 1000 // 1 hour

app.get('/api/translations/:locale', async (req, res) => {
  const { locale } = req.params
  const cacheKey = `translations:${locale}`

  // Check cache
  const cached = cache.get(cacheKey)
  if (cached && cached.expires > Date.now()) {
    res.setHeader('X-Cache', 'HIT')
    return res.json(cached.data)
  }

  try {
    const response = await fetch(
      `${API_URL}/projects/${PROJECT_ID}/translations/${locale}`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    )

    if (!response.ok) {
      return res.status(response.status).json({ error: 'Failed to fetch' })
    }

    const data = await response.json()

    // Cache the result
    cache.set(cacheKey, { data, expires: Date.now() + CACHE_TTL })

    res.setHeader('Cache-Control', 'public, max-age=3600')
    res.setHeader('X-Cache', 'MISS')
    res.json(data)
  } catch (error) {
    res.status(500).json({ error: 'Internal server error' })
  }
})

Client Usage

Your frontend fetches from your proxy, not LocaleLens directly:

// Instead of calling LocaleLens directly:
// fetch('https://localelens.ai/api/v1/projects/xxx/translations/en')

// Call your own backend:
const response = await fetch('/api/translations/en')
const translations = await response.json()

Caching Strategy

In most applications, translations change infrequently. Aggressive caching reduces latency, API usage, and costs.

Recommended TTLs

Production1-24 hours
Staging5-15 minutes
DevelopmentNo cache

Cache Headers

Cache-Control: public, s-maxage=3600

Allows CDN caching for 1 hour

stale-while-revalidate=86400

Serve stale content while fetching fresh data

Cache Invalidation

When you update translations in LocaleLens, cached versions will serve until TTL expires. For immediate updates:

•Purge your CDN cache (Vercel, Cloudflare, etc.)
•Clear your application cache
•Or wait for TTL to expire (simplest approach)

API Key Rotation

Rotate API keys periodically or when team members leave. LocaleLens supports multiple active keys per project for zero-downtime rotation.

Zero-Downtime Rotation

Create a new API key in Project Settings → API Keys
Deploy the new key to your production environment
Verify your application works with the new key
Revoke the old key once confirmed

Best Practices

•Use environment variables, never hardcode keys
•Use different keys for production, staging, and development
•Rotate keys quarterly or after security incidents
•Monitor for unexpected API key usage in your dashboard

Rate Limits & Usage Tracking

LocaleLens uses monthly API request limits. With proper caching, even high-traffic applications stay well within limits.

API Limits

Free1,000 requests/month
Pro100,000 requests/month

Limits apply to the account owner, not team members.

When Limits are Exceeded

•API returns 429 Too Many Requests
•Includes Retry-After header
•Resets on the 1st of each month

Monitoring Usage

Track your API usage in the LocaleLens dashboard:

•Usage & Billing page — view current month's usage
•80% warning — shown in the dashboard when approaching limits
•Response headers — include remaining quota info

Reducing API Usage

1.Cache aggressively — 1 hour TTL covers most use cases
2.Use a CDN — Vercel, Cloudflare, etc. cache at the edge
3.Fetch once per deploy — bundle translations at build time (for static or infrequently updated apps)
4.Avoid client-side fetching — each user visit = 1 request

Documentation