What the agent does
The agent reads how the site is laid out before it adds a language, because Starlight infers almost everything about i18n from directory names. In a site like the basics example in withastro/starlight, package.json depends on @astrojs/starlight ^0.42.7, astro ^7.2.10 and sharp, with dev, build and preview scripts. astro.config.mjs passes title: 'My Docs', a GitHub social link and a sidebar with two groups: Guides, whose one item is { label: 'Example Guide', slug: 'guides/example' }, and Reference, which uses autogenerate: { directory: 'reference' }. src/content.config.ts defines only the docs collection with docsLoader() and docsSchema(). The content is three files: src/content/docs/index.mdx with template: splash, a hero whose actions link to /guides/example/, and a CardGrid; guides/example.md; and reference/example.md. There is no locales, no defaultLocale and no src/content/i18n/ directory, so the site is the monolingual English default. The Linear issue that starts the run names the language to add.
The first decision is where English lives. Starlight's own i18n guide offers two layouts: every language in its own folder (src/content/docs/en/, src/content/docs/fr/), which moves every existing page to /en/..., or a root locale that keeps one language at the top level. The agent chooses root, so /guides/example/ keeps answering and no inbound link breaks: in astro.config.mjs it adds locales: { root: { label: 'English', lang: 'en' }, fr: { label: 'Français', lang: 'fr' } }, with lang set on the root locale because the guide requires it there, and leaves defaultLocale out, which the guide allows when the root locale is the default. title becomes an object keyed by language tag so the header reads in each language. On the Guides group and its Example Guide item it adds translations: { fr: 'Guides' } and translations: { fr: "Guide d'exemple" }, the property the sidebar reference uses for per-language labels; the autogenerated Reference group needs none, because its entries take each page's own frontmatter title.
Then the pages. The agent creates src/content/docs/fr/index.mdx, fr/guides/example.md and fr/reference/example.md with the same file names as the English originals, since that is how Starlight pairs pages across languages, and translates each title and description plus the body. In the French index.mdx the hero's actions link becomes /fr/guides/example/ and the external link to the Starlight docs stays. The translations are marked as drafts for a native speaker in the pull request, because a machine draft that reads as final is worse than one that says what it is. Any page left untranslated still has a URL: Starlight serves the English content under /fr/ with a notice that the page is not yet translated, so the agent can also stop after index.mdx if the issue asks for a skeleton only.
Starlight ships its own interface strings, the search label, the table of contents heading, the language picker, in a set of built-in languages, French among them. For a language it does not ship, or when the issue asks for different wording, the agent adds the i18n data collection to src/content.config.ts with i18nLoader() and i18nSchema() and a src/content/i18n/<tag>.json that translates only the values of the keys it overrides, including the expressiveCode.* and pagefind.* keys for code blocks and search. It then runs npm install and npm run build in its sandbox, checks that dist/guides/example/index.html still exists and that dist/fr/index.html, dist/fr/guides/example/index.html and dist/fr/reference/example/index.html were written, reads the <html lang> attribute of one English and one French page, and confirms the language picker appears in the header. npm run preview serves the result so it can request /fr/guides/example/ and a deliberately untranslated path to see the fallback notice.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a second language to this Starlight documentation site; the language is named in the Linear issue that follows. Read package.json, astro.config.mjs, src/content.config.ts and every file under src/content/docs first. Configure locales in astro.config.mjs with the existing language as the root locale, with lang set, so current URLs do not change, and add the new locale with its label and lang. Make title an object with a value per language. Add translations for the new language to every sidebar group and link that has a label. Create a translated copy of every page under src/content/docs/<locale>/ with the same file names, translating frontmatter and body and adjusting internal links to the locale prefix; mark the translations as drafts to be reviewed by a native speaker. If Starlight does not ship UI strings for the language, add the i18n collection to src/content.config.ts and a src/content/i18n/<tag>.json with translated values. Run the build, check that the old URLs and the new locale pages exist in dist, check the html lang attribute and the language picker, and open a pull request that links the issue and lists every page translated.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 that changes astro.config.mjs and, when needed, src/content.config.ts, and adds the src/content/docs/<locale>/ tree with one file per English page, plus a src/content/i18n/<tag>.json when the language is not among Starlight's built-in UI translations. The description lists every page it translated with its English counterpart, states which are drafts for review, and pastes the astro build summary showing the page count and the paths under dist/<locale>/.
The run's record keeps the build output, the dist/ listing and the preview requests, so a reviewer can see that /guides/example/ still builds at the root and that the French page carries lang="fr" before opening the branch.
Before merging, a reviewer reads the translations, decides whether the root-locale layout is right for a site that may add more languages, and checks the sidebar in the new language, where an autogenerated group shows each page's translated frontmatter title. Content, components and styles outside the configuration and the new locale directory are unchanged.
Run it on every Linear issue labelled i18n
Add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled with i18n in its labels. Labelling an issue such as "Add German docs" starts one run in the Project's repository; the trigger adds the issue after the prompt, so the agent reads the language from the issue and the prompt text itself never changes. A change made by a Linear app integration never fires the trigger, and the automation starts at most max_runs_per_hour runs in an hour.
From your own server, the same run starts with this request and the issue's URL added to resources as https://linear.app/<workspace>/issue/<ID>, which puts the issue in the prompt through your Linear connection. Give the key a webhook URL and Rush POSTs run.completed with data.session_url when the turn ends, so a handler can post the pull request link back on the issue.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Adding a language to a docs site is many small, consistent edits: one config change, one file per page in the right folder with the right name, every internal link re-prefixed, and the labels that live in config rather than in content. Done by hand, the usual failure is one forgotten page that silently falls back to English or one link that points at the unprefixed path. The agent reads the whole content tree first and does the same thing to every file, then builds the site to prove the pages exist.
On Rush the build runs in the run's own sandbox with the output kept, and each language request is its own run with its own pull request, so a team can hand three languages to three runs at once and review each on its own. The pull request says which strings are drafts, which is what a translator needs to start.
Frequently asked questions
Will my existing URLs change?
Not with the layout the agent chooses. A root locale keeps the current language's pages directly under src/content/docs/ and their paths unprefixed, so /guides/example/ keeps working. Only the new language gets a prefix such as /fr/. The other layout, a folder per language including the current one, moves every page to /en/... and needs redirects; the pull request notes that this is a one-line change if you prefer it.
What happens to pages I have not translated yet?
Starlight serves them. A request for /fr/some-page/ with no French file shows the content from the default language with a notice that the page is not yet translated. That is why the agent uses the same file names across locales: the pairing is what makes the fallback work, and it means you can translate progressively.
Does Starlight translate its own interface?
For the languages it ships UI strings for, yes: the search label, the table of contents heading and the rest change with the locale, and the language picker appears once more than one locale is configured. For another language, or to change the wording, the i18n collection in src/content.config.ts and a JSON file per language under src/content/i18n/ override the defaults key by key, including Expressive Code and Pagefind strings.
How are the sidebar labels translated?
Link and group entries in the sidebar config take a translations object keyed by language tag, and the plain label is used for the default locale and any language without a translation. Autogenerated groups need no entry, because each page's translated frontmatter title is what appears. The agent adds translations to every entry that has a label and leaves the autogenerated group alone.
More Starlight jobs
The same job on other stacks
- Add i18n to a SvelteKit App from a Linear Issue (SvelteKit)
- Add i18n to a Tauri App (Tauri)
- Add i18n to a Vite React App from a Linear Issue (Vite + React)