# Add i18n to an Eleventy Blog

Yes. An agent moves your Eleventy content under one directory per language, turns on the built-in I18n plugin, translates the layouts and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/eleventy/). 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 site is wired. In a blog like 11ty/eleventy-base-blog, `package.json` pins `@11ty/eleventy` ^3.1.7 as an ES module project with `build` running `npx @11ty/eleventy` and `.nvmrc` naming Node 22. `eleventy.config.js` sets `dir.input` to `content`, includes to `../_includes` and data to `../_data`, and registers the navigation, RSS feed, syntax highlight, image transform, HTML base and `IdAttribute` plugins. `_data/metadata.js` carries `language: "en"`, which `_includes/layouts/base.njk` writes into `<html lang>`; the same layout builds the top menu from `collections.all | eleventyNavigation`. English strings sit in the templates themselves: `Latest 3 Posts` and `more posts can be found in the archive` in `content/index.njk`, `Archive` in `blog.njk`, `Tags` and `Tagged` in the tag pages, `Previous` and `Next` in `layouts/post.njk`, `Skip to main content` and `Built with` in the base layout, and `Content not found` in `404.md`.

Then it restructures the content the way Eleventy's own `I18nPlugin` expects: the first directory segment is the language. `content/blog/*.md`, `index.njk`, `blog.njk`, `about.md` and the tag pages move to `content/en/`, with `git mv` so history follows, and a `content/fr/` tree holds the French versions with the same file names. `eleventy.config.js` gains `addPlugin(I18nPlugin, { defaultLanguage: "en" })`, which gives every page a `page.lang` and the `locale_url` and `locale_links` filters. The hard-coded UI strings move to `_data/strings.js`, keyed by language, and the layouts read them through `page.lang`; `base.njk` writes `page.lang` into `<html lang>` instead of the single `metadata.language`, and the `readableDate` filter in `_config/filters.js` passes the page language to Luxon's `setLocale` so French posts show French month names.

Two details in this repository need care. `eleventy-navigation` requires unique keys, so the French pages get their own keys and the menu in `base.njk` lists only entries whose URL starts with the current page's locale prefix, with a language switcher built from `locale_links` beside it. And `collections.posts` now holds both languages, so the agent adds a filter that keeps the items whose `page.lang` matches and applies it in `index.njk`, `blog.njk` and the previous and next links in `post.njk`. `sitemap.xml.njk` already declares the `xmlns:xhtml` namespace, so each `<url>` gains `xhtml:link rel="alternate" hreflang` entries from `locale_links`. The Atom feed keeps `language: "en"` and its `posts` collection filtered to English; the pull request names a second feed as a follow-up rather than guessing.

The root `/` becomes a small page that lists the languages and redirects to `/en/`, and the pull request notes that `netlify.toml` and `vercel.json` both exist for a host-level redirect later. The proof is the build: `npm run build` completes, `_site/en/` and `_site/fr/` contain the same set of pages, which the agent checks with a short script that compares the two file lists, every page's `<html lang>` matches its directory, and the feed and sitemap still parse.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add internationalization to this Eleventy blog. Read package.json, eleventy.config.js, _config/filters.js, _data/metadata.js, every layout in _includes and every template in content first. Move the existing English content under content/en with git mv, add French under content/fr with the same file names, and enable Eleventy's built-in I18nPlugin with en as the default language. Move every hard-coded UI string in the layouts and templates into a strings data file keyed by language, write page.lang into the html lang attribute, make the navigation show only the current language plus a language switcher, filter the posts collection by language on the home, archive, tag and previous/next views, add hreflang alternates to the sitemap, pass the language to the date filter, and keep the Atom feed English. Mark the French text as a draft for a native speaker. Run npm run build, check that the en and fr output trees have the same pages and that every page's lang attribute matches its directory, and open a pull request that lists each string you moved.",
  "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 with the moved `content/en/` tree, the new `content/fr/` tree, the `I18nPlugin` registration in `eleventy.config.js`, `_data/strings.js`, the edited layouts in `_includes`, the language-aware `readableDate` filter, the `hreflang` lines in `sitemap.xml.njk` and the new root index. `package.json` and the lockfile are untouched, because the plugin ships inside `@11ty/eleventy`.

The description lists every string that left a template and the key it now has, the pages in each language, and the output of the build with the two file lists side by side. The commands and their output are in the transcript at `GET /o/{org}/sessions/{id}/messages`, so a reviewer can see the build without running it.

Before merging, a reviewer asks a French speaker to read `content/fr/`, opens the built site from `_site/` to click through both language trees, and decides whether to drop the `/en/` prefix for the default language with a permalink rule, which the pull request describes but does not do. A follow-up message to the same session adds a third language with the same keys.

## Run it on every Linear issue labelled i18n

A team that tracks localization in Linear starts one run per issue from an automation with a `linear` trigger on the `i18n` label. The automation adds the issue after this prompt, so a language the issue asks for, or a page it says is missing a translation, is what the agent reads, and the run starts in the repository the automation names.

Each run opens its own pull request from its own sandbox, and an automation run has its own `max_runs_per_hour` cap. The pull request links the issue and lists the strings and pages it touched, so the translator's review is a read of the new language directory and the strings file.

## Why run it on Rush?

The work in localizing a static site is not the plugin line; it is moving every page without breaking a URL, finding each English word hidden in a template, and proving the two language trees stay in step. The agent does the finding by reading the templates, uses the plugin the site's own framework ships, and treats a clean build with matching file lists as the test, in its own sandbox with Node 22 and the real dependencies installed.

The pull request carries that proof in the transcript: the build output, the file-list comparison and the `lang` check sit beside the commands that produced them. Several sites can be handled at once, each in its own sandbox, with one pull request each.

## Frequently asked questions

### Do my URLs change?

Yes, by the language prefix: `/blog/firstpost/` becomes `/en/blog/firstpost/`. The pull request keeps the root as a redirect to `/en/` and explains how a permalink rule in a directory data file can drop the prefix for the default language if the team prefers the old paths.

### Does the agent need a third-party plugin?

No. The `I18nPlugin` is part of `@11ty/eleventy` 3, which the repository already pins, so nothing new is installed. The UI strings live in a plain data file under `_data/` rather than a translation library.

### Who writes the French text?

The agent drafts it, keeping the same front matter, tags and dates as the English posts, and marks it as a draft for a native speaker in the pull request. The structure, the keys and the matching file lists are what the run guarantees; the wording is for a reviewer who speaks the language.

### What happens to the Atom feed and the sitemap?

The feed stays English, with its collection filtered so French posts do not appear in it, and the pull request names a second feed as a follow-up. The sitemap gains `hreflang` alternates for every page that has a translation, using the `locale_links` filter the plugin provides.

## More Eleventy jobs

- [Show a Last Updated Date from Git History on Eleventy Posts](https://getrush.ai/run/add-last-modified-dates/eleventy/)
- [Add Lighthouse CI to an Eleventy Site](https://getrush.ai/run/add-lighthouse-ci/eleventy/)
- [Check for Broken Links in an Eleventy Site's CI](https://getrush.ai/run/add-link-checking/eleventy/)

## The same job on other stacks

- [Add i18n to an Expo App](https://getrush.ai/run/add-i18n/expo/)
- [Add Internationalisation to a Filament Admin Panel from a Linear Issue](https://getrush.ai/run/add-i18n/filament/)
- [Add i18n to a Flutter App](https://getrush.ai/run/add-i18n/flutter/)

## 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/)
