How SiteLocaleAI Works

Architecture Overview

SiteLocaleAI is split into two parts: a lightweight JS library that runs in your visitor's browser, and a Node.js SDK that runs on your server. Here is the full request flow.

SiteLocaleAI architecture: Browser JS Library connects to your Node.js SDK, which calls your LLM provider

Your website content never passes through our servers. We only verify your license key when the SDK boots.

1

Add the JS Library

One script tag. Works with any website.

The SiteLocaleAI JS library is a lightweight, zero-dependency script (~15KB gzipped) that you add to your HTML. It handles everything on the client side:

Locale detection — Reads the visitor's browser language preferences and geo-IP data to determine their preferred language and currency.
Translation requests — Sends page text to your SDK backend for translation. Only untranslated content is sent; cached translations are served instantly.
DOM text swapping — Replaces visible text on the page with translated versions, preserving HTML structure, attributes, and event handlers.
Price localization — Detects elements marked with data-price attributes and converts them to the visitor's local currency with proper formatting.
Language switcher — Renders an optional language picker UI that visitors can use to manually switch languages.

Add to your HTML <head>

<!-- SiteLocaleAI — drop-in translation -->
<meta name="sitelocaleai:url" content="https://your-sdk.example.com">
<meta name="sitelocaleai:locales" content="en,de,fr,es,ja">
<meta name="sitelocaleai:default-locale" content="en">
<meta name="sitelocaleai:base-currency" content="USD">
<script src="https://cdn.jsdelivr.net/npm/sitelocaleai/dist/sitelocaleai.iife.js"></script>

Price localization markup

<!-- Mark prices for automatic conversion -->
<span data-price="49" data-currency="USD">
  $49/month
</span>

<!-- Visitor in Germany sees: 45 EUR/Monat -->
<!-- Visitor in Japan sees: 7,400 JPY/month -->

docker-compose.yml

services:
  sdk:
    image: ghcr.io/hiscore-ro/sitelocaleai-sdk
    ports:
      - "3100:3100"
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/slai
      LICENSE_KEY: slai_your_license_key
      OPENAI_API_KEY: sk-your-openai-key
    depends_on:
      - db

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_DB: slai
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

2

Deploy the SDK

Your server, your keys, your data.

The SiteLocaleAI SDK is a Node.js application that runs on your own infrastructure. It handles:

Translation engine — Receives translation requests from the JS library, calls your configured LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API), and returns translated text.
PostgreSQL caching — Every translation is cached in your PostgreSQL database. The first request for a page triggers an LLM call; every subsequent request for the same content is served from cache in under 5ms.
Admin dashboard — A React-based admin panel served at /admin where you manage languages, review translations, edit cached content, and monitor usage.
License verification — On startup, the SDK makes a single API call to api.sitelocaleai.com to verify your license key and plan tier. This is the only time your SDK contacts our servers.

Deploy with Docker (recommended), or run directly with Node.js. The SDK supports any hosting provider — AWS, DigitalOcean, Hetzner, Railway, Fly.io, or your own hardware.

docker-compose.yml

services:
  sdk:
    image: ghcr.io/hiscore-ro/sitelocaleai-sdk
    ports:
      - "3100:3100"
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/slai
      LICENSE_KEY: slai_your_license_key
      OPENAI_API_KEY: sk-your-openai-key
    depends_on:
      - db

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_DB: slai
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

3

Configure Languages

Manage everything from the admin dashboard.

Once the SDK is running, open the admin dashboard at https://your-sdk.example.com/admin. From there you can:

Add languages — Enable any of 100+ supported languages. Each language gets its own translation cache.
Review translations — Browse translated content page by page. Edit any translation manually if the LLM output needs adjustment.
Set translation rules — Define glossary terms, brand names that should not be translated, and tone preferences per language.
Monitor usage — Track translation requests, cache hit rates, LLM API costs, and visitor language distribution.
Configure price localization — Set supported currencies, exchange rate sources, and psychological pricing rules (e.g., round to .99).

SiteLocaleAI admin dashboard — manage languages, review translations, monitor usage

CLI pre-rendering

# Install the CLI tool
npm install -g sitelocaleai-cli

# Pre-render all pages in all languages
sitelocaleai prerender \
  --sitemap https://example.com/sitemap.xml \
  --languages en,de,fr,es,ja \
  --output ./dist/i18n

# Output structure:
# dist/i18n/de/index.html
# dist/i18n/de/pricing.html
# dist/i18n/fr/index.html
# dist/i18n/fr/pricing.html
# ...

# Deploy to your CDN or server
rsync -avz ./dist/i18n/ user@server:/var/www/i18n/

4

SEO Pre-rendering Optional

Static HTML for every language. Google indexes each version.

The SiteLocaleAI CLI tool generates static HTML pages for every language variant of your site. This is critical for international SEO because search engines need crawlable, indexable HTML — they cannot execute JavaScript to discover translated content.

Reads your sitemap — The CLI fetches your sitemap.xml and pre-renders every URL in every configured language.
Generates static HTML — Each page gets a fully-rendered HTML file with translated content, proper <html lang="..."> attributes, and hreflang link tags.
CI/CD friendly — Run the CLI in your build pipeline. New content is automatically pre-rendered on every deploy.
Deploy anywhere — Upload the generated files to your CDN, S3 bucket, or web server. Serve /de/pricing for German, /fr/pricing for French.

Available on the Growth plan ($99/month) and above. The Indie and Starter plans use client-side translation only.

CLI pre-rendering

npm install -g sitelocaleai-cli

sitelocaleai prerender \
  --sitemap https://example.com/sitemap.xml \
  --languages en,de,fr,es,ja \
  --output ./dist/i18n

Under the Hood

Technical details for developers and architects.

Translation Caching

The first time a visitor loads a page in a new language, the SDK sends the source text to your LLM provider and stores the translation in PostgreSQL. Every subsequent request for the same content is served directly from the database — typically in under 5ms.

Cache keys are based on a hash of the source text, target language, and your translation rules. If you update your source content, a new translation is generated automatically. Old translations are retained for rollback.

Price Localization

The JS library detects the visitor's currency from their IP address using a lightweight geo-IP lookup. It then applies real-time exchange rates (from your configured provider) and optional psychological pricing rules.

Psychological pricing rounds converted amounts to attractive price points — for example, converting $49 USD to EUR might yield 44.97 EUR, which gets rounded to 44.99 EUR. You configure rounding rules per currency in the admin dashboard.

SEO & Indexing

The CLI tool generates static HTML with proper <html lang="de"> attributes, <link rel="alternate" hreflang="de"> tags, and canonical URLs for each language variant. Search engines can crawl and index each version independently.

This means your German pages rank in Google.de, your French pages rank in Google.fr, and your Japanese pages rank in Google.co.jp — each with proper language signals that search engines understand.

Dynamic Content, Caching & Performance

SiteLocaleAI is built for real-world websites with dynamic content, user-generated text, and constantly changing pages.

Smart Translation Cache

Every translated segment is stored in PostgreSQL with a composite cache key: a SHA-256 hash of the source text, target language, and your translation rules. This means:

First visit: LLM translates the text (typically 200-800ms depending on length)
All subsequent visits: Served from PostgreSQL cache in <5ms
Browser cache: Translations also stored in localStorage for instant rendering on repeat visits
Content change detection: When source text changes, a new translation is triggered automatically. Old translations are retained for instant rollback.

Typical LLM costs: ~$0.002 per page translation with GPT-4o mini. A 100-page site in 5 languages costs roughly $1 to translate fully, then $0 ongoing from cache.

Dynamic Content Handling

Unlike static translation tools, SiteLocaleAI handles dynamic and user-generated content in real time:

DOM MutationObserver: The JS library watches for DOM changes (AJAX loads, SPA navigations, infinite scrolling) and translates new content as it appears
Template variables: Preserves {{name}}, {count} and similar interpolation patterns during translation
Selective translation: Mark elements with data-no-translate to skip code blocks, brand names, or user input fields
Batch requests: Groups multiple text segments into a single LLM call for efficiency, reducing API overhead by up to 80%

Works with React state updates, Vue reactivity, HTMX swaps, Turbo frames, and any JavaScript-driven content changes.

Currency Exchange & Price Localization

The price localization engine handles the full pipeline from detection to display:

Geo-IP detection: Determines visitor country from IP address using a bundled MaxMind-compatible database (no external API calls on each request)
Exchange rate caching: Fetches rates from your configured provider (ECB, OpenExchangeRates, or custom) and caches them in the SDK. Rates refresh every 4 hours by default.
Psychological pricing: Converts and rounds to attractive price points per currency. $49 USD becomes EUR 45 (not EUR 47.23). Rules are configurable per currency.
Format-aware display: Renders prices in the correct locale format: $49.00, 45,00 EUR, 7,400 JPY, 39.00 GBP with proper currency symbols and separators
150+ currencies: Supports all ISO 4217 currencies including crypto price display

Performance Optimizations

Every layer of the stack is optimized for speed:

15KB JS library: Zero dependencies, tree-shaken, gzipped. Loads with defer attribute so it never blocks page rendering
Three-tier cache: Browser localStorage (instant) -> SDK in-memory cache (microseconds) -> PostgreSQL (milliseconds). LLM API is only called on true cache misses.
Lazy translation: Only visible text is translated on initial load. Below-the-fold content is translated as the user scrolls (IntersectionObserver-based)
Connection pooling: SDK uses connection pooling for PostgreSQL (via Prisma) and keep-alive connections to LLM providers
Streaming responses: Translations are streamed back to the browser as they complete, so partial page content appears before the full translation finishes

Core Web Vitals impact: negligible. The JS library adds <50ms to Time to Interactive on a 3G connection.

Security & Privacy

SiteLocaleAI is architected with privacy as the default. Unlike cloud-hosted translation services that route all your content through their servers, SiteLocaleAI keeps everything on your infrastructure.

What stays on your servers:

All your website content and page text
All translated content and translation cache
Your LLM API keys (OpenAI, Anthropic, etc.)
Your visitor data, analytics, and usage logs
Your PostgreSQL database with all translation data

What we see:

Your license key (verified once on SDK boot)
Your domain name (to match the license)
Your plan tier (to enforce feature limits)

That is it. No content. No visitor data. No analytics.

GDPR-Friendly by Design

Because your content and visitor data never leave your infrastructure, SiteLocaleAI simplifies GDPR compliance. You control the data processor (your LLM provider), the data storage (your database), and the data retention (your policies). No third-party DPA required with us — we do not process your visitors' personal data.

Performance

Fast by default. No runtime latency after first load.

15KB

JS library (gzipped)

Zero runtime dependencies. Loads asynchronously with defer. No impact on your Largest Contentful Paint (LCP) or First Input Delay (FID).

<5ms

Cached translation response

After the first translation, all subsequent requests are served from PostgreSQL. No LLM API call needed. Translations are also cached in the browser's localStorage for instant rendering on repeat visits.

0ms

Pre-rendered pages

With the SEO CLI, translated pages are static HTML files. No JavaScript execution needed, no API calls, no network latency. The translated content is already in the HTML that the server sends to the browser.