Tutorial

How to Pre‑Render Multilingual Gatsby Pages for Google SEO

Published July 16, 2026

How to Pre‑Render Multilingual Gatsby Pages for Google SEO

How to Pre‑Render Multilingual Gatsby Pages for Google SEO

Google loves fully rendered HTML. When you serve a static Gatsby site, you can take advantage of SiteLocaleAI to generate translated versions of every page at build time, ensuring search engines index the exact content users see. This tutorial shows a practical workflow for a static Gatsby site, from installing the library to running the CLI and verifying the results.

1. Prerequisites

  • Node.js ≥ 18 and npm or yarn installed.
  • A Gatsby project (gatsby new my-site).
  • Access to an LLM API key (Claude, GPT‑4o‑mini, etc.) – SiteLocaleAI works with any provider you prefer.
  • Basic knowledge of GraphQL and Gatsby’s page creation.

2. Install the SiteLocaleAI JavaScript library

SiteLocaleAI is a drop‑in, framework‑agnostic library. Add it to your Gatsby project:

npm install @sitelocaleai/core
# or
yarn add @sitelocaleai/core

3. Configure your LLM API key

Create a .env.production file (or use your CI secret manager) and add the key:

SITELOCALEAI_API_KEY=YOUR_API_KEY_HERE
SITELOCALEAI_PROVIDER=claude   # or openai, etc.

In gatsby-config.js expose the variable to the browser safely:

require('dotenv').config({ path: '.env.production' });

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-env-variables',
      options: {
        whitelist: ['SITELOCALEAI_API_KEY', 'SITELOCALEAI_PROVIDER'],
      },
    },
    // other plugins
  ],
};

4. Add the SiteLocaleAI script to your pages

Create a small wrapper component that loads the library and registers translation hooks. Place it in src/components/LocaleProvider.js:

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

const LocaleProvider = ({ children }) => {
  useEffect(() => {
    initLocaleAI({
      apiKey: process.env.SITELOCALEAI_API_KEY,
      provider: process.env.SITELOCALEAI_PROVIDER,
      // optional: set default language and rounding rules
      defaultLang: 'en',
      rounding: { USD: 0.99, EUR: 0.95 },
    });
  }, []);

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

export default LocaleProvider;

Wrap your root element in gatsby-browser.js:

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

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

Now every page can call window.localeAI.translate(text, targetLang) at runtime, but we will pre‑render translations in the next step.

5. Generate translation JSON files (optional)

If you prefer to keep translation data separate, you can run a one‑off script that pulls all translatable strings from your source files and stores them in src/translations/. This is useful for large sites.

// scripts/extractStrings.js
const fs = require('fs');
const path = require('path');
const glob = require('glob');

const files = glob.sync('src/**/*.js');
const strings = new Set();

files.forEach((file) => {
  const content = fs.readFileSync(file, 'utf8');
  const matches = content.match(/t\(['"]([^'"]+)['"]\)/g) || [];
  matches.forEach((m) => strings.add(m.slice(3, -2)));
});

fs.writeFileSync(
  path.join(__dirname, '..', 'src', 'translations', 'source.json'),
  JSON.stringify(Array.from(strings), null, 2)
);

Run it with node scripts/extractStrings.js. The resulting source.json will be consumed by the CLI.

6. Pre‑render translations with the SiteLocaleAI CLI

SiteLocaleAI ships a CLI that can crawl your built Gatsby public/ folder, translate each HTML file, and write language‑specific copies (e.g., public/es/, public/fr/). Install the CLI globally or as a dev dependency:

npm install -D @sitelocaleai/cli
# or
yarn add -D @sitelocaleai/cli

Add a script to package.json:

{
  "scripts": {
    "build": "gatsby build",
    "translate": "sitelocaleai translate --src public --langs es,fr,de,ja --rounding"
  }
}

Run the full pipeline:

npm run build && npm run translate

The CLI will:
1. Load each HTML file.
2. Send translatable text to your LLM via the API key.
3. Apply psychological rounding for prices (e.g., $9.99 → $9.99, €19.95 → €19.95).
4. Write the translated HTML to language subfolders.

You now have a static, SEO‑ready multilingual site that Google can crawl without JavaScript execution.

7. SEO – – update gatsby-plugin-react-helmet

Add language‑specific <link rel="alternate" hreflang="..."> tags so Google knows which version to serve to each user.

// src/components/SeoHelmet.js
import React from 'react';
import { Helmet } from 'react-helmet';

const SeoHelmet = ({ title, description, lang, path }) => (
  <Helmet>
    <title>{title}</title>
    <meta name="description" content={description} />
    <html lang={lang} />
    {/* Alternate links */}
    <link rel="alternate" hrefLang="en" href={`https://example.com${path}`} />
    <link rel="alternate" hrefLang="es" href={`https://example.com/es${path}`} />
    <link rel="alternate" hrefLang="fr" href={`https://example.com/fr${path}`} />
    <link rel="alternate" hrefLang="de" href={`https://example.com/de${path}`} />
    <link rel="alternate" hrefLang="ja" href={`https://example.com/ja${path}`} />
  </Helmet>
);

export default SeoHelmet;

Use SeoHelmet in your page templates, passing the language detected from the URL.

8. Deploy and verify

Deploy the public/ folder to any static host (Netlify, Vercel, AWS S3, etc.). After deployment, use Google Search Console → URL Inspection to fetch each language version. You should see the translated content in the rendered HTML.

If you need to troubleshoot, the CLI offers a --debug flag that logs the LLM responses.

9. Internal resources

10. Ready to go global?

With just a few commands, your Gatsby site becomes a multilingual powerhouse that Google indexes instantly. Try SiteLocaleAI today, boost international traffic, and watch your conversions rise.

Start your free trial →

Back to blog