# Add i18n to a Gatsby Blog

Yes. An agent adds a second locale to a Gatsby blog, moves the hardcoded UI strings into translation files, builds every locale and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/gatsby/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts by reading how the blog is put together, because a Gatsby starter has no i18n layer to hook into. In a repository shaped like gatsbyjs/gatsby-starter-blog it finds a `package.json` on Gatsby 5.14 with `gatsby-source-filesystem`, `gatsby-transformer-remark`, `gatsby-plugin-feed` and `gatsby-plugin-manifest`, React 18, Prettier 2.8 as the only dev dependency, no lockfile other than `package-lock.json`, and a `test` script that only prints a reminder to write tests and exits 1. It reads `gatsby-config.js`, where `siteMetadata` holds the title, author summary and description in English, and `gatsby-node.js`, where `createPages` queries `allMarkdownRemark`, builds one page per post at `fields.slug` with `previousPostId` and `nextPostId` in context, and `createSchemaCustomization` declares the `Frontmatter` type with `title`, `description` and `date`. It reads `gatsby-ssr.js`, which sets `lang: en` on the HTML element for every page.

Then it lists every string a reader sees that is not post content: the footer in `src/components/layout.js` ("Built with"), the "Written by" and "You should follow them on Twitter" lines in `src/components/bio.js`, "All posts" in the `Head` of `src/pages/index.js`, "404: Not Found" and its sentence in `src/pages/404.js`, the "No blog posts found" fallback, and the date format `MMMM DD, YYYY` baked into the GraphQL queries of `index.js` and `src/templates/blog-post.js`. Post files live at `content/blog/<slug>/index.md` with `title`, `date` and `description` frontmatter and nothing that names a language.

The change adds `gatsby-plugin-react-i18next` with `react-i18next` and `i18next`, a `locales/<lang>/translation.json` directory sourced through a second `gatsby-source-filesystem` entry, and the plugin's `languages`, `defaultLanguage` and `siteUrl` options in `gatsby-config.js`, so the default language stays at `/` and the new one is served under its prefix. In `gatsby-node.js` the agent makes `createPages` read `node.fields.locale`, which it derives in `onCreateNode` from a `content/blog/<slug>/index.<lang>.md` filename and defaults to the default language, and it extends `createSchemaCustomization` so a post without a translation still resolves. The components switch to the plugin's `Link` and `useTranslation`, the `Head` exports read their titles through `t()`, the date format moves into the translation file, and the `lang` attribute in `gatsby-ssr.js` follows the page's language instead of the constant `en`. The RSS feed in `gatsby-plugin-feed` keeps producing `/rss.xml` from the default-language posts only, and the agent says so in the pull request.

Before it pushes anything the agent runs `npm ci`, `npm run build` and `npm run serve`, then fetches `/`, `/<lang>/`, one post in each language and the 404 page from the served build to check the strings and the `lang` attribute, and runs `npm run format` so Prettier's `semi: false` and `arrowParens: avoid` settings from `.prettierrc` hold across the new files. It adds one translated copy of an existing post under `content/blog/` so the pull request shows the full path from Markdown to rendered page.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add internationalisation to this Gatsby blog with gatsby-plugin-react-i18next. Keep the current language at / and add one more language under its own prefix. Move every visible UI string in src/components, src/pages and src/templates into locales/<lang>/translation.json, make gatsby-node.js create one page per post per language from content/blog/<slug>/index.<lang>.md files with a fallback to the default language, and make the html lang attribute follow the page. Translate one existing post as an example, run npm run build and check the served pages, then open a pull request that lists what moved and what did not.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch. Its diff touches `package.json` and `package-lock.json` for the three new packages, `gatsby-config.js` for the plugin block and the `locales` source, `gatsby-node.js` for the per-language page creation and the schema additions, `gatsby-ssr.js` for the `lang` attribute, the three components under `src/components`, the pages under `src/pages`, `src/templates/blog-post.js`, two `translation.json` files and one translated post. The description lists each string that moved, the URL scheme for the second language, and the places it chose not to touch, such as the RSS feed.

The proof is in the session rather than in the description. The trajectory at `GET /o/{org}/sessions/{id}/messages` keeps the `npm run build` output with the page count Gatsby reports, the curl calls against the served site and the HTML they returned, so a reviewer can see the translated footer and the `lang` attribute without checking the branch out. If the build fails at any step the run does not open a pull request; it ends with the failing output in its result.

Before merging, a reviewer checks that the default-language URLs did not change, since the starter's feed and any inbound links depend on them, that the translation files hold every string the components used to inline, and that a post without a translated copy still renders in the second language rather than producing a 404. They also check the date format in each translation file reads naturally in that language.

## Run it on every new language added to the site

A team that adds languages one at a time sends `POST /o/{org}/sessions` with this prompt each time, naming the language in the prompt and the repository in `resources`. The first run adds the plugin and the locale files; a later run reads the `languages` array already in `gatsby-config.js`, adds one entry and one `translation.json`, and translates the same example post, so each run is a pull request a reviewer can read in one sitting.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when the turn ends, with `session_url` to read the pull request from. A `request_id` that is a UUID v5 of the language code makes a retried request return the run it already started instead of opening a second pull request.

## Why run it on Rush?

Adding i18n to a Gatsby site is a long edit across config, node APIs and every component, followed by a full build to see whether the GraphQL schema still resolves. On Rush the run happens in its own cloud sandbox: it installs with `npm ci`, runs `gatsby build` with the sharp image pipeline the starter depends on, and serves the result to read the pages back, while your working tree and your `.cache` directory stay as they were.

The result is checkable rather than claimed. The pull request carries the diff, the trajectory keeps every `npm` command with its output, and the served pages the agent fetched are in the record, so the review is about whether the strings read well in the new language, not about whether the build passes.

## Frequently asked questions

### Which i18n plugin does it use?

The pull request uses `gatsby-plugin-react-i18next`, which wraps `react-i18next` and `i18next` and adds a language-aware `Link` and page duplication per language. If your prompt names another approach, such as `gatsby-plugin-intl`, the agent uses that instead and the pull request description says which one it chose and why.

### Will the URLs of my existing posts change?

No. The default language stays unprefixed, so `/hello-world/` keeps resolving, and only the added language is served under its prefix. The reviewer's checklist in the pull request includes this, and the agent's curl calls against the served build cover one default-language post.

### What happens to a post that has no translation?

The agent makes `createPages` fall back to the default-language Markdown when no `index.<lang>.md` exists, so the page exists in the second language with translated UI around untranslated content. The pull request names this behaviour, and you can ask for a hidden page instead with a follow-up on the same session.

### Does it translate my posts?

It translates one existing post as a worked example so the pull request shows the file naming and the rendered result. Translating the rest of `content/blog` is editorial work the pull request leaves to you; the mechanism it adds works for any post you add a translated copy of.

### The starter has no tests. How do I know it works?

The starter's `test` script exits 1 on purpose, so the agent does not rely on it. It relies on `gatsby build` succeeding and on fetching the served pages, and both are kept in the trajectory at `GET /o/{org}/sessions/{id}/messages`. Your own CI, if any, runs on the pull request as usual.

## More Gatsby jobs

- [Add Lighthouse CI to a Gatsby Blog](https://getrush.ai/run/add-lighthouse-ci/gatsby/)
- [Add Pagination to a Gatsby Blog Index](https://getrush.ai/run/add-pagination/gatsby/)
- [Add PWA Support to a Gatsby Blog](https://getrush.ai/run/add-pwa-support/gatsby/)

## The same job on other stacks

- [Add i18n to a Hugo Site](https://getrush.ai/run/add-i18n/hugo/)
- [Add i18n to a Leptos App](https://getrush.ai/run/add-i18n/leptos/)
- [Add Localization to a Lit Web Component with @lit/localize](https://getrush.ai/run/add-i18n/lit/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
