All jobs

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

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

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading