tstlai: Just-In-Time AI Localization

tstlai is middleware for Just-In-Time AI localization with intelligent caching to minimize costs and latency.

Why tstlai?

Traditional i18n requires maintaining separate JSON files for each language - extracting strings, syncing changes across files, and coordinating with translators. As your app grows, this becomes a maintenance burden that slows down development.

tstlai takes a different approach:

• One source of truth - Maintain a single JSON file or write inline. Either way, you never sync multiple language files.
• Add languages instantly - One line of config. No translation workflow, no waiting on translators.
• Context-aware accuracy - Unlike standard auto-translation, AI understands context. "Save" translates correctly whether it's a button, a discount, or a rescue mission.
• Pay once per string - Intelligent caching means each unique string is translated only once.

How It Works

1. You write your app in your source language
2. tstlai intercepts text at render time (or build time)
3. New strings are translated via AI and cached
4. Cached translations are served instantly on subsequent requests

The result: your app supports any language without changing your development workflow.

Features

• HTML-Safe - Only text nodes are translated; structure, classes, and attributes stay intact
• RTL Support - Automatic dir and lang attributes for Arabic, Hebrew, Persian, etc.
• Flexible Caching - Redis for production, in-memory for development
• Multiple Integration Modes - Auto-translate, server-side, or CLI generation at build time
• Framework Support - Next.js, Express, Fastify, Astro, Remix

Installation

npm install tstlai

Quick Start

import { Tstlai } from 'tstlai';

const translator = new Tstlai({
  targetLang: 'es',
  provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY },
  cache: { type: 'memory' },
});

// Translate text
const translated = await translator.translateText('Hello, world!');

// Or process full HTML
const result = await translator.process('<h1>Hello</h1>');
console.log(result.html); // <h1>Hola</h1>

Documentation

| Guide | Description | | :----------------------------------------------------------- | :----------------------------------------- | | Quick Start | 5 minutes to a translated app | | Configuration | All options, env vars, caching | | Next.js Integration | Auto-translate, SSR, next-intl migration | | CLI Generate | Static file generation for CI/CD | | Frameworks | Express, Fastify, Astro, Remix | | Caching | Redis setup, multi-language keys |

Integration Methods

| Method | Best For | Setup | | :-------------------- | :------------------------- | :-------------------- | | Auto-Translate | Legacy apps, fastest setup | Drop-in component | | Page Translations | New projects | List strings upfront | | JSON Adapter | next-intl migration | Use existing JSON | | CLI Generate | Static sites, mobile apps | Build-time generation |

Environment Variables

| Variable | Description | Default | | :---------------- | :--------------- | :-------------------------- | | OPENAI_API_KEY | OpenAI API Key | — | | OPENAI_MODEL | Model ID | gpt-3.5-turbo | | OPENAI_BASE_URL | Custom endpoint | https://api.openai.com/v1 | | REDIS_URL | Redis connection | redis://localhost:6379 |

CLI

# Generate Spanish and French from English source
npx tstlai generate -i locales/en.json -o locales/ -l es,fr

# With context for better quality
npx tstlai generate -i en.json -l de,ja -c "E-commerce website"

Preventing Translation

<span data-no-translate>BrandName™</span>

Or use excludedTerms in config for global exclusions.

Security

tstlai includes built-in protections and provides guidance for secure deployments:

Built-in Protections

• XSS Safe - Translations are applied via textContent, not innerHTML
• Request Limits - Route handlers enforce default limits (100 texts, 100K chars per request)
• Production Warnings - Console warnings alert you to add rate limiting

Safest Option: Server-Side Only

Use createPageTranslations or CLI generate to avoid exposing any public endpoint:

// No public API needed—runs entirely on your server
const t = await createPageTranslations(translator, ['Welcome', 'About us']);
return <h1>{t('Welcome')}</h1>;

If Using Client-Side Translation

When exposing translation endpoints (e.g., for AutoTranslate), you must implement:

• Rate limiting - Prevent API abuse and cost overruns
• Origin validation - Restrict access to your domains
• Monitoring - Track usage and set billing alerts with your AI provider

// Example: Customize limits
export const POST = createNextRouteHandler(translator, {
  maxTexts: 50, // Stricter limit
  maxTotalChars: 25000,
});

⚠️ Without rate limiting, your endpoint is exploitable. An attacker can use your AI credits for free translations.

📖 Full Security Guide - Rate limiting examples, origin validation, complete protected route implementation.

License

MIT

tstlai is developed by Zaguán AI, a 100% OpenAI-compatible API that makes it easy to switch between models.