# Add i18n to a Docusaurus Site

Yes. An agent adds the i18n config, a locale dropdown, the i18n/<locale> folders with extracted labels and copied docs, a build per locale, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/docusaurus/). 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 built before it adds a locale. In a site laid out like testing-library/testing-library-docs, `docusaurus.config.js` sets `title: 'Testing Library'`, `url: 'https://testing-library.com'` and `baseUrl: '/'`, loads `@docusaurus/preset-classic` with the docs at `./docs` (`sidebarPath: './sidebars.js'`, `editUrl` pointing at the repository, `showLastUpdateTime`), a blog at `./blog`, Algolia search with `indexName: 'testing-library'`, and a `colorMode` block, but no `i18n` block, and there is no `i18n/` directory. `package.json` pins `@docusaurus/core` and `@docusaurus/preset-classic` at `^2.0.1` with React 16, and its `write-translations`, `examples`, `version` and `rename-version` scripts still call the Docusaurus v1 binaries (`docusaurus-write-translations`), which v2 does not ship. `.node-version` says 16.14. `netlify.toml` builds with `npm install; npm run format; npm run build`, publishes `build`, and ends with a catch-all rule that sends `/docs/*` to `/docs/dom-testing-library/:splat`. `docs/` holds 114 files across per-framework directories such as `react-testing-library`, `dom-testing-library`, `queries` and `user-event`; `src/pages` has `index.js`, `help.js` and `users.js`, whose visible strings are plain JSX text.

It fixes the v1 scripts first, so `npm run write-translations` runs `docusaurus write-translations`. Then it adds `i18n: { defaultLocale: 'en', locales: ['en', 'es'] }` to the config (the prompt names the locale), and `{ type: 'localeDropdown', position: 'right' }` to `themeConfig.navbar.items` beside the Help and Blog links. Running `npm run write-translations -- --locale es` writes `i18n/es/code.json`, `i18n/es/docusaurus-theme-classic/navbar.json` and `footer.json`, and `i18n/es/docusaurus-plugin-content-docs/current.json` with the sidebar category labels from `sidebars.js` ('Getting Started', 'Examples', 'Help'). Because the three pages under `src/pages` use raw strings, the agent wraps their headings, buttons and captions in `<Translate>` from `@docusaurus/Translate` so they appear in `code.json` with the English text as the default message; the `users` list in `customFields` stays untranslated, since it holds company names.

For the content it follows the Docusaurus tutorial: `docs/` is copied to `i18n/es/docusaurus-plugin-content-docs/current/` and `blog/` to `i18n/es/docusaurus-plugin-content-blog/`, so every page exists under `/es/` from the first build, in English until a translator replaces it. The agent translates the pages the prompt names (`intro.mdx` and `guiding-principles.mdx` by default) and leaves the rest as copies, with a `TRANSLATING.md` note on how to add a page. Each copied `.mdx` keeps its `id` front matter, so the sidebar resolves the same ids in both locales. Because `editUrl` points at `docs/`, it sets `editLocalizedFiles: true` on the docs plugin so the edit link on a Spanish page opens the file under `i18n/`. With `onBrokenLinks: 'log'` already in the config, a link that only exists in one locale is listed at build time instead of failing it.

It builds every locale with `npm run build` (`build/` for English, `build/es/` for Spanish) and checks one locale at a time with `npm run start -- --locale es`. Two deployment details change: the Netlify catch-all for `/docs/*` does not cover `/es/docs/*`, so the agent adds the matching rule for the new prefix, and since Algolia's crawler configuration lives outside the repository it turns on `contextualSearch` in `themeConfig.algolia` so results are limited to the locale being read, and says in the pull request that the crawler must index the `/es/` pages before Spanish search returns anything.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Spanish (es) as a second locale to this Docusaurus 2 site. Read docusaurus.config.js, package.json, sidebars.js, netlify.toml, the files under src/pages and the layout of docs/ and blog/ first. Fix any package.json scripts that still call Docusaurus v1 binaries so that docusaurus write-translations works. Add an i18n block with defaultLocale en and locales en and es, add a localeDropdown item to the navbar, and wrap the visible strings in src/pages in <Translate>. Run write-translations for es, copy docs/ and blog/ into the i18n/es content folders, translate docs/intro.mdx and docs/guiding-principles.mdx into Spanish, and set editLocalizedFiles on the docs plugin. Add a Netlify redirect for /es/docs/* that mirrors the existing /docs/* rule and enable contextualSearch for Algolia. Run npm run build and confirm build/ and build/es/ are produced, then open a pull request that lists every new folder and says which pages are translated and which are English copies.",
  "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

The pull request changes `docusaurus.config.js` (the `i18n` block, the `localeDropdown` item, `editLocalizedFiles`, `contextualSearch`), `package.json` (the four v1 script names), the three files under `src/pages` (strings wrapped in `<Translate>`), `netlify.toml` (one redirect rule), and adds the `i18n/es/` tree: `code.json`, `navbar.json`, `footer.json`, `current.json`, the copied docs and blog posts, and the two translated pages. Its description lists the folders, names the pages that are real translations, and quotes the build output showing both locales.

A reviewer opens the English site from the branch and confirms nothing moved: the default locale still lives at the root, the sidebar ids are unchanged, and the dropdown appears on every page. On `/es/`, they read the two translated pages, click an edit link and check it lands under `i18n/es/`, and try a deep link such as `/es/docs/queries/about` to see the new Netlify rule behave like the old one. The copied English pages are the part to decide on: ship them so the Spanish site is complete, or hide the locale behind a feature branch until more pages are translated.

Nothing in the pull request claims the search index covers Spanish. That is a change on the Algolia side, and the description says so.

## Run it on every Linear issue labelled i18n

An automation on the Project with a `linear` trigger on `linear.issue.labeled` and the label `i18n` starts one run per request for a new language. The trigger adds the issue after the prompt and fills in no placeholder, so the prompt tells the agent to read the locale code from the issue title and to reuse the `i18n` block, the dropdown and the Netlify rule the first locale added. A second language is then a smaller change: one more entry in `locales`, one more content folder, one more redirect.

A team that maintains several Docusaurus sites sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming that repository in `resources` and carrying a `request_id` that is a UUID v5 of the repository name and the locale, so a retried call returns the run already started instead of a second one.

## Why run it on Rush?

Adding a locale is mostly mechanical and mostly waiting: fixing stale scripts, running the extraction command, copying over a hundred files into the right plugin folders, wrapping page strings, and building every locale to see what the dropdown and the edit links do. The agent does that in its own sandbox with the site's own Node version, keeps every command and its output, and hands back a branch whose build has already produced `build/es/`.

A reviewer reads a config diff and two translated pages instead of a how-to. The same request runs against every docs site a team owns at once, each in its own sandbox, each reading its own config.

## Frequently asked questions

### Does the agent translate every page?

No. It copies every page so the locale builds complete, and translates the pages the prompt names. Machine-translating a whole reference by default would ship text nobody reviewed; the pull request lists which files are translations and which are English copies so a translator can take over.

### Will the English site change?

The default locale keeps its URLs, sidebar ids and edit links. The visible changes on English pages are the locale dropdown in the navbar and, if `contextualSearch` is on, search results filtered to English. The `<Translate>` wrappers in `src/pages` render the same English text as before.

### Why fix the package.json scripts first?

In this site `write-translations` still runs the v1 binary `docusaurus-write-translations`, which is not installed with `@docusaurus/core` 2. The agent points it at `docusaurus write-translations` so the extraction step works from `npm run`, and does the same for the `examples`, `version` and `rename-version` scripts.

### Does search work in the new locale?

Docusaurus can scope results per locale with `contextualSearch`, but the pages must be in the Algolia index first, and the crawler configuration is not in the repository. The pull request says so and leaves that step to whoever owns the DocSearch application.

### What about Netlify and the /docs/* redirect?

The existing rule only matches paths under `/docs/`, so the agent adds a sibling for `/es/docs/*`. Netlify applies these rules only when no file exists at the path, which is why the comment in `netlify.toml` says the route is not redirected when it is not a 404; the new rule inherits that behaviour.

## More Docusaurus jobs

- [Add Lighthouse CI to a Docusaurus Site](https://getrush.ai/run/add-lighthouse-ci/docusaurus/)
- [Find and Fix Broken Links in a Docusaurus Site](https://getrush.ai/run/add-link-checking/docusaurus/)
- [Add llms.txt to a Docusaurus Docs Site](https://getrush.ai/run/add-llms-txt/docusaurus/)

## The same job on other stacks

- [Add i18n to an Electron App from a Linear Issue](https://getrush.ai/run/add-i18n/electron/)
- [Add i18n to an Eleventy Blog](https://getrush.ai/run/add-i18n/eleventy/)
- [Add i18n to an Expo App](https://getrush.ai/run/add-i18n/expo/)

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