Framework Guide

Pre‑rendered Multilingual Gatsby Sites with SiteLocaleAI

Published August 10, 2026

Pre‑rendered Multilingual Gatsby Sites with SiteLocaleAI

Pre‑rendered Multilingual Gatsby Sites with SiteLocaleAI

Google loves fully rendered HTML. For static sites built with Gatsby, you can combine the speed of a static generator with the power of SiteLocaleAI’s self‑hosted translation engine to serve pre‑translated pages that are instantly indexable. This tutorial walks you through the entire workflow – from installing the library to generating SEO‑friendly static pages.

1. Prerequisites

  • A Gatsby site (v5 or later) generated with gatsby new.
  • An LLM API key (Claude, GPT‑4o‑mini, etc.) that you will pass to SiteLocaleAI.
  • Node >= 18 installed locally.
  • Access to the SiteLocaleAI documentation at https://sitelocaleai.com/docs.

2. Install the SiteLocaleAI library

SiteLocaleAI is a framework‑agnostic JavaScript bundle. Install it as a regular npm dependency:

npm install @sitelocaleai/core

Tip: The library is tiny (≈ 15 KB gzipped) and works with any bundler Gatsby uses under the hood.

3. Add the translation script to your layout

Create a new component, e.g., src/components/LocaleProvider.jsx, that loads the library and initializes it with your LLM key.

import React, { useEffect } from 'react'
import { initLocale } from '@sitelocaleai/core'

const LocaleProvider = ({ children }) => {
  useEffect(() => {
    // The key is stored in an environment variable for security.
    const apiKey = process.env.GATSBY_LOCALEAI_API_KEY
    initLocale({
      apiKey,
      // Enable price rounding for the target currency.
      priceLocalization: true,
      // Optional: restrict output to a specific schema.
      schema: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          price: { type: 'string' },
        },
        required: ['title', 'price']
      }
    })
  }, [])

  return <>{children}</>
}

export default LocaleProvider

Wrap your root layout with this provider (e.g., in gatsby-browser.js):

import React from 'react'
import LocaleProvider from './src/components/LocaleProvider'

export const wrapRootElement = ({ element }) => (
  <LocaleProvider>{element}</LocaleProvider>
)

4. Mark translatable content

SiteLocaleAI scans the DOM for elements with the data-locale-key attribute. Add this attribute to any text you want translated.

<h1 data-locale-key="home.title">Welcome to Our Store</h1>
<p data-locale-key="home.tagline">Best prices worldwide</p>
<span data-locale-key="product.price">$19.99</span>

When the page loads, the library replaces the inner text with the translated version based on the visitor’s language.

5. Pre‑render translations for SEO

Google can’t execute JavaScript for every language variant, so we pre‑render each locale using the SiteLocaleAI CLI. Install the CLI globally:

npm install -g @sitelocaleai/cli

Then run the rendering command. The CLI crawls your built site, fetches translations from the LLM, and writes a new static folder for each locale.

n build   # Build the original Gatsby site first
npx sitelocaleai prerender \
  --source public \
  --output public-localized \
  --locales en,es,fr,de,ja \
  --api-key $LOCALEAI_API_KEY \
  --price-rounding true
  • --source points to the Gatsby output folder.
  • --output is where the localized static files will be written.
  • --locales is a comma‑separated list of ISO‑639‑1 codes.
  • --price-rounding activates psychological rounding (e.g., $19.99 → $19.95).

The CLI creates sub‑folders like public-localized/en, public-localized/es, etc., each containing a fully translated index.html.

6. Deploy the localized build

Upload the public-localized folder to your static host (Netlify, Vercel, AWS S3, etc.). Configure a rewrite rule so that /es/* serves files from public-localized/es/*, and similarly for other locales.

For Netlify, add a _redirects file:

/*   /en/:s   200!
/es/*   /es/:s   200!
/fr/*   /fr/:s   200!
/de/*   /de/:s   200!
/ja/*   /ja/:s   200!

Now every language path returns a fully rendered HTML page, which Google can crawl and index.

7. Verify SEO with the URL Inspection tool

  1. Open Google Search Console → URL Inspection.
  2. Enter https://yourdomain.com/es/ (or any locale).
  3. The tool should show a Rendered HTML that already contains the translated text and price values.
  4. If the page is indexed, you’ll see the language tag (<html lang="es">).

8. Optional: WordPress‑style fallback

If you have a hybrid site that pulls content from a headless WordPress instance, you can still use the same data-locale-key pattern. No additional Node.js runtime is required because the translation happens at build time via the CLI.

9. Keep your LLM usage in check

SiteLocaleAI lets you control token limits per locale. In sitelocaleai.config.json you can set a maximum token budget:

{
  "tokenBudget": 50000,
  "fallbackLocale": "en"
}

When the budget is exhausted, the CLI falls back to the source language, ensuring your build never fails.

10. Wrap‑up

You now have a static Gatsby site that serves pre‑rendered, SEO‑friendly translations for multiple languages, all powered by your own LLM API key. This approach combines the speed of static hosting with the nuance of AI‑driven localization, giving you a competitive edge in international search.

Ready to international your site multilingual without sacrificing performance? Try SiteLocaleAI today and see how easy it is to boost your global reach.

---Internal links for further reading:
- Getting started: https://sitelocaleai.com/docs/getting-started
- CLI reference: https://sitelocaleai.com/docs/cli

Back to blog