Tutorial

Pre‑rendered Multilingual Gatsby Sites with SiteLocaleAI

Published April 1, 2026

Pre‑rendered Multilingual Gatsby Sites with SiteLocaleAI

Published on SiteLocaleAI Blog • 2026‑04‑01

Introduction

Gatsby’s static‑site generation (SSG) gives you lightning‑fast pages, but delivering those pages in multiple languages can be tricky. Traditional client‑side translation libraries load after the page is rendered, which means search‑engine crawlers see only the default language. SiteLocaleAI solves this by letting you pre‑render translated HTML at build time while keeping the library self‑hosted and framework‑agnostic.

In this tutorial you’ll learn how to:

  1. Add the SiteLocaleAI JavaScript library to a Gatsby project.
  2. Configure it to use your own LLM API key (Claude, GPT‑4o‑mini, etc.).
  3. Generate language‑specific pages with the built‑in CLI for SEO‑friendly pre‑rendering.
  4. Deploy the multilingual site so Google indexes every language version.

By the end, your site will serve fully translated HTML to crawlers, improve international SEO, and keep your LLM costs under control.

Prerequisites

  • Node.js ≥ 18 and npm or yarn.
  • A Gatsby site (gatsby new my‑site).
  • An LLM API key (Claude, GPT‑4o‑mini, etc.).
  • Basic knowledge of environment variables and the command line.

1. Install SiteLocaleAI

Open a terminal in your Gatsby project root and run:

npm i @sitelocaleai/core

The package is a drop‑in, framework‑agnostic JavaScript library. It works with React, Vue, WordPress, Shopify, or any static site generator.

2. Add the library to your layout

Create a src/components/LocaleProvider.jsx (or .tsx if you use TypeScript) that injects the translation script globally:

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

const LocaleProvider = ({ children }) => {
  useEffect(() => {
    // Initialise SiteLocaleAI with your LLM key and target languages
    initLocale({
      apiKey: process.env.GATSBY_LLM_API_KEY,
      languages: ["en", "es", "fr", "de"],
      defaultLang: "en",
      priceRounding: true, // enable psychological rounding
    });
  }, []);

  return <>{children}</>;
};

export default LocaleProvider;

Wrap your root layout (gatsby-browser.js) with the provider:

import React from "react";
import LocaleProvider from "./src/components/LocaleProvider";

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

Tip: Keep the library client‑side only; the pre‑render step (next section) will replace the HTML with translated content.

3. Configure environment variables

Create a .env.production file (or add to your existing .env) with the LLM key:

GATSBY_LLM_API_KEY=YOUR_CLAUDE_OR_GPT4O_MINI_KEY

Gatsby automatically prefixes variables with GATSBY_ for client‑side exposure.

4. Define translation settings

SiteLocaleAI reads a JSON configuration that tells it which strings to translate and how to localize prices. Add a locale.config.json at the project root:

{
  "priceRounding": true,
  "currencyMap": {
    "USD": "$",
    "EUR": "€",
    "GBP": "£",
    "JPY": "¥"
  },
  "psychologicalRounding": {
    "USD": 0.99,
    "EUR": 0.95,
    "GBP": 0.99,
    "JPY": 0
  }
}

The library will automatically apply these rules when it encounters price strings like $19.99.

5. Pre‑render translations with the CLI

SiteLocaleAI ships a CLI tool that crawls your built HTML, sends translatable fragments to the LLM, and writes language‑specific files. Install the CLI globally (or as a dev dependency):

npm i -D @sitelocaleai/cli

Add a script to package.json:

"scripts": {
  "build": "gatsby build",
  "locale:pre": "sitelocaleai pre-render --config locale.config.json --out-dir public"
}

Now run the full build and pre‑render pipeline:

npm run build && npm run locale:pre

The CLI will:
1. Read the generated public/ folder.
2. For each page, request translations for the languages defined in LocaleProvider.
3. Write files like public/es/index.html, public/fr/index.html, etc.

Because the output is static HTML, Google can crawl and index every language without JavaScript execution.

6. Verify the output

Start a local server to inspect the generated pages:

npm i -g serve
serve -s public

Visit http://localhost:5000/es/ and you should see the Spanish version of your site, with prices rounded to $19.99 → $19.99 (or $19.95 for EUR, etc.).

7. Deploy

Deploy the public/ folder to any static‑hosting provider (Netlify, Vercel, AWS S3, Cloudflare Pages). The language‑specific URLs are already present, so no additional rewrite rules are required.

8. SEO considerations

  • Canonical tags: Add a <link rel="canonical" href="https://example.com/" /> on each language page, and use <link rel="alternate" hreflang="es" href="https://example.com/es/" /> for the others. SiteLocaleAI can inject these automatically if you enable seo: true in the config.
  • Sitemap: Regenerate your sitemap after the pre‑render step. Tools like gatsby-plugin-sitemap will pick up the new language folders.
  • Meta tags: Use the same seo_title and seo_desc values for each language, translated via the LLM. You can fetch them from the LLM at build time and store them in locale.config.json.

For a deeper dive into SEO‑specific settings, see the official docs: https://sitelocaleai.com/docs/seo.

9. Optional: WordPress plugin alternative

If you ever need to migrate this setup to WordPress, SiteLocaleAI offers a Node‑free plugin that performs the same pre‑rendering on the server side. Check the docs for a quick switch: https://sitelocaleai.com/docs/wordpress.

Conclusion

By combining Gatsby’s static generation with SiteLocaleAI’s self‑hosted translation engine, you get instant, SEO‑friendly multilingual pages without sacrificing performance or incurring huge LLM costs. The CLI‑based pre‑rendering ensures that search engines see the exact content you want indexed, while the library’s price‑localization features boost conversion rates across markets.

Ready to boost your global reach? Try SiteLocaleAI today and see how easy it is to turn any static site into a multilingual powerhouse.

Back to blog