# Add i18n to a Starlight Docs Site

Yes. An agent adds locales to your Starlight site, keeps English at the root so no URL changes, adds translated pages, sidebar labels and UI strings, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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

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

- [Check for Broken Links in a Starlight Docs Site](https://getrush.ai/run/add-link-checking/starlight/)
- [Add llms.txt to a Starlight Docs Site](https://getrush.ai/run/add-llms-txt/starlight/)
- [Add Mermaid Diagrams to a Starlight Docs Site](https://getrush.ai/run/add-mermaid-diagrams/starlight/)

## The same job on other stacks

- [Add i18n to a SvelteKit App from a Linear Issue](https://getrush.ai/run/add-i18n/sveltekit/)
- [Add i18n to a Tauri App](https://getrush.ai/run/add-i18n/tauri/)
- [Add i18n to a Vite React App from a Linear Issue](https://getrush.ai/run/add-i18n/vite-react/)

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