All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading