Seo Guide

Boost International SEO with Pre‑Rendered Gatsby Translations

Published June 14, 2026

Boost International SEO with Pre‑Rendered Gatsby Translations

Boost International SEO with Pre‑Rendered Gatsby Translations

Published on SiteLocaleAI Blog

International traffic is a goldmine for any e‑commerce or content site, but Google only indexes what it can crawl. For static sites built with Gatsby, the key to winning global rankings is to serve fully translated HTML to search bots. In this guide we’ll walk through a complete workflow using SiteLocaleAI, a self‑hosted JavaScript library that leverages your own LLM API keys, price localization, and a powerful CLI for SEO‑friendly pre‑rendering.

1. Why Pre‑Render Translations?

Google’s crawler executes JavaScript, but it may not wait for asynchronous translation calls, especially when they depend on external LLM APIs. Pre‑rendering translations at build time guarantees that each language version is a static HTML page, which:

  • Improves crawlability – search engines see the final content instantly.
  • Boosts Core Web Vitals – no extra client‑side latency.
  • Enables accurate indexing – meta tags, structured data, and price formatting are already localized.

SiteLocaleAI’s CLI (sitelocale-cli) integrates seamlessly with Gatsby’s build pipeline, turning your markdown or MDX content into a set of language‑specific HTML files.

2. Prerequisites

Requirement Details
Node.js v18+
Gatsby v5+
SiteLocaleAI npm package @sitelocaleai/js
LLM API key Claude, GPT‑4o‑mini, or any compatible endpoint
Currency data Optional JSON for psychological rounding

Make sure you have a self‑hosted LLM key – SiteLocaleAI never stores your prompts.

3. Install the Library

npm install @sitelocaleai/js

The library is framework‑agnostic, so you can drop it into any component. In Gatsby we’ll create a small wrapper that loads the translation data generated by the CLI.

4. Configure SiteLocaleAI

Create a sitelocale.config.js file at the project root:

module.exports = {
  // Your LLM endpoint – keep it secret!
  llmEndpoint: process.env.LLM_API_URL,
  llmKey: process.env.LLM_API_KEY,
  // Target languages (ISO‑639‑1)
  locales: ["en", "es", "de", "fr", "ja"],
  // Price localization settings
  priceConfig: {
    rounding: "psychological", // 9.99 → 9.95, 19.99 → 19.95, etc.
    currencyMap: {
      USD: "$",
      EUR: "€",
      JPY: "¥"
    }
  }
};

Tip: Store the keys in a .env file and add it to .gitignore.

5. Generate Translations with the CLI

SiteLocaleAI ships a CLI that reads your source content (Markdown, JSON, or any string) and writes language‑specific files to a folder you specify.

npx sitelocale-cli generate \
  --src ./src/content \
  --out ./src/localized \
  --config ./sitelocale.config.js

The command performs:
1. Content extraction – pulls text nodes from your pages.
2. LLM translation – sends batches to your LLM using the provided API key.
3. Price localization – applies psychological rounding per currency.
4. File output – creates en.json, es.json, etc., inside ./src/localized.

You can run this step locally before every Gatsby build, or add it to a CI pipeline.

6. Hook Translations into Gatsby

Create a small helper to load the JSON at runtime:

// src/utils/useLocale.js
import { useStaticQuery, graphql } from "gatsby";

export const useLocale = (locale = "en") => {
  const data = useStaticQuery(graphql`
    query {
      allFile(filter: { sourceInstanceName: { eq: "localized" } }) {
        nodes {
          name
          publicURL
        }
      }
    }
  `);

  const file = data.allFile.nodes.find(node => node.name === locale);
  const [messages, setMessages] = React.useState({});

  React.useEffect(() => {
    if (file) {
      fetch(file.publicURL)
        .then(res => res.json())
        .then(setMessages);
    }
  }, [file]);

  return messages;
};

Now use it in any page component:

import React from "react";
import { useLocale } from "../utils/useLocale";

const ProductPage = ({ data }) => {
  const locale = typeof window !== "undefined" ? window.location.pathname.split("/")[1] : "en";
  const t = useLocale(locale);

  return (
    <section>
      <h1>{t["product.title"] || data.title}</h1>
      <p>{t["product.description"] || data.description}</p>
      <p>{t["product.price"] || `$${data.price}`}</p>
    </section>
  );
};

export default ProductPage;

When Gatsby builds the site, the JSON files are copied to the public folder, and the page renders the pre‑translated strings instantly.

7. SEO‑Friendly Pre‑Rendering

Gatsby already produces static HTML, but you must ensure each locale has its own URL and proper <link rel="alternate" hreflang> tags. Update gatsby-.js:

module.exports = {
  siteMetadata: {
    siteUrl: "https://example.com",
    title: "My International Store",
  },
  plugins: [
    {
      resolve: "gatsby-plugin-react-helmet",
    },
    {
      resolve: "gatsby-plugin-sitemap",
      options: {
        exclude: ["/admin/*"],
      },
    },
    {
      resolve: "gatsby-plugin-i18n",
      options: {
        locales: ["en", "es", "de", "fr", "ja"],
        defaultLocale: "en",
        path: "slug",
      },
    },
  ],
};

Add the alternate links in your layout component:

import { Helmet } from "react-helmet";

const Layout = ({ children }) => {
  const locale = typeof window !== "undefined" ? window.location.pathname.split("/")[1] : "en";
  const locales = ["en", "es", "de", "fr", "ja"];

  return (
    <>
n      <Helmet>
        {locales.map(l => (
          <link
            rel="alternate"
            hreflang={l}
            href={`https://example.com/${l}`}
            key={l}
          />
        ))}
      </Helmet>
      {children}
    </>
  );
};

export default Layout;

Now each language version is a distinct, crawlable URL with proper hreflang annotations, which Google uses to serve the right language to users.

8. Testing Before Deploy

  1. Local preview – run gatsby develop and switch locales via the URL.
  2. Validate markup – use Google’s Rich Results Test and URL Inspection tools.
  3. Check price formatting – ensure the psychological rounding appears as expected (e.g., $9.95 instead of $9.99).

For a deeper dive into the CLI options, see the official docs: https://sitelocaleai.com/docs/cli and https://sitelocaleai.com/docs/integration.

9. Deploy

When you’re satisfied, build the static site:

npm run build

Upload the public/ folder to your hosting provider (Netlify, Vercel, AWS S3, etc.). Because the translations are baked into the HTML, search engines will index every locale without additional JavaScript execution.

10. Wrap‑Up

By combining SiteLocaleAI’s self‑hosted translation engine with Gatsby’s static generation, you get:

  • Lightning‑fast, SEO‑ready multilingual pages.
  • Full control over LLM usage and costs.
  • Precise price localization that boosts conversion.

Ready to dominate international search results? Try SiteLocaleAI today and transform your static site into a global traffic magnet.

Back to blog