All jobs

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

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading