All jobs

Add i18n to a MkDocs Site

Yes. An agent adds mkdocs-static-i18n to a Material for MkDocs site with a second language, suffixed pages, a switcher and a fallback, builds it 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 the site before it adds a plugin. In a project laid out like encode/httpx, mkdocs.yml names the material theme with custom_dir: 'docs/overrides' (one partial, partials/nav.html), a two-scheme palette with light and dark toggles, a nav of 23 Markdown pages grouped under Introduction, QuickStart, Advanced, Guides, API Reference and Community, and markdown_extensions of admonition, codehilite and mkautodoc, the extension that renders ::: httpx.Client directives in api.md from docstrings. There is no plugins key, so the default search plugin is active implicitly. requirements.txt pins the docs toolchain: mkdocs==1.6.1, mkautodoc==0.2.0, mkdocs-material==9.6.18. scripts/docs runs mkdocs serve, scripts/build runs mkdocs build after the package build, and .github/workflows/test-suite.yml runs that script on Python 3.9 to 3.13; scripts/publish deploys with mkdocs gh-deploy --force, and docs/CNAME carries the domain.

It adds mkdocs-static-i18n==1.3.1 under the documentation pins in requirements.txt, a release that requires mkdocs>=1.5.2 and, for its Material integration, mkdocs-material<9.7.2, both satisfied here. Because adding a plugins key disables the implicit default, the list it writes is search first and then i18n, with docs_structure: suffix, fallback_to_default: true, reconfigure_material: true, reconfigure_search: true, and a languages list: en as default: true with name: English, and the requested second locale, say ja with name: 日本語. The suffix structure means the English pages keep their names (index.md, quickstart.md) and a translation sits beside each as index.ja.md; untranslated pages fall back to English under /ja/ instead of disappearing from the Japanese nav. nav_translations on the ja entry maps the section titles (Introduction, QuickStart, Advanced, Guides, API Reference, Community) and the page titles, because the nav is defined once in mkdocs.yml and only its labels need translating.

The translated pages are the work a reviewer will judge, so the agent translates a small, representative set rather than everything at once: index.ja.md and quickstart.ja.md, keeping every fenced code block, admonition and link target byte for byte, and leaves api.ja.md out, because that page is generated by mkautodoc from English docstrings and a copy would only duplicate them. Material's language switcher appears on its own once reconfigure_material is on, pointing each page at its own alternate; the theme.language override on the ja entry switches Material's built-in labels, and reconfigure_search keeps the fallback copies out of search results. The custom partials/nav.html override is checked against both builds, since a theme override is the one place the switcher can be lost.

It runs scripts/build and reads the i18n plugin's log for missing translations and nav mismatches, opens site/index.html and site/ja/index.html in the sandbox browser to check the switcher, the palette toggle and the search, and opens the pull request when the build is clean.

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 the MkDocs documentation in this repository, with Japanese as the first target. Read mkdocs.yml, requirements.txt, docs/, docs/overrides, scripts/docs, scripts/build and .github/workflows first. Add mkdocs-static-i18n to the pinned docs requirements, and add a plugins list that keeps search and configures i18n with the suffix docs structure, fallback to the default language, Material reconfiguration and search reconfiguration, English as the default and Japanese as the second language with nav_translations for every nav label. Translate the index and quickstart pages as index.ja.md and quickstart.ja.md, keeping every code block, admonition and link exactly as it is, and leave the mkautodoc-generated API pages untranslated. Confirm the language switcher works with the existing theme override, run scripts/build until it is clean, check both languages in the browser, and open a pull request that lists the translated pages, the fallback pages and the build output.",
  "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 requirements.txt by one pinned line and mkdocs.yml by a plugins block, and adds docs/index.ja.md and docs/quickstart.ja.md. Its description shows the mkdocs build log from the sandbox, names which pages are translated and which fall back to English under /ja/, and shows the two URLs the switcher moves between.

A reviewer who reads the target language checks the two translations for meaning and for untouched code samples; one who does not checks the build log, the nav labels and that /ja/api/ still renders the English docstrings rather than an empty page. The search entry at the top of the new plugins list is worth a glance, because leaving it out silently removes search from the site.

From then on a translator adds a page by creating its .ja.md neighbour; nothing in mkdocs.yml changes, and an untranslated page keeps showing English until its translation lands.

Run it on every new language request

A maintainer who takes translation offers as GitHub issues adds an automation to the Project with a github trigger on issues.labeled, the label i18n, and this prompt with the language left to the issue. The trigger appends the issue after the prompt and fills in no placeholder, so the agent reads the language from the issue text ("Korean docs" adds a ko entry and index.ko.md) while the prompt stays fixed. Only an issue labelled by an owner, member or collaborator fires it, and the automation's max_runs_per_hour caps how many languages it starts in an hour.

A team that documents several packages the same way sends this body once per repository from its own server, each a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own mkdocs.yml: a site that already lists plugins gets i18n appended after them, and one on the folder structure gets docs/ja/ instead of suffixed files.

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

Why run it on Rush?

The plugin configuration is short, but the mistakes are quiet: a plugins key that drops search, a translated page whose code block was reflowed, a theme override that hides the switcher, a generated API page copied into a second language. Catching them means building the site and clicking through both languages, which the agent does in its own sandbox with the pinned versions from requirements.txt, and the build log comes back with the pull request.

Translation is also a task that starts many times, once per language and once per site, and each start is the same request with one word changed. Running them on Rush means each language lands as its own reviewable pull request, started from an issue label or from a loop over repositories, without a maintainer setting up the toolchain for each.

Frequently asked questions

Why the suffix structure rather than a folder per language?

With suffixes the English pages keep their current names and URLs, so nothing already linked or deployed with mkdocs gh-deploy moves, and a translation is a file beside its original. The folder structure (docs/en/, docs/ja/) is the better fit for a site that starts bilingual; the plugin supports both, and the prompt can ask for the folder layout instead.

What happens to pages nobody has translated yet?

With fallback_to_default: true the /ja/ build includes the English version of every untranslated page, so the Japanese nav is complete from day one. reconfigure_search removes those copies from search results so each hit appears once. The pull request lists which pages are real translations and which are fallbacks.

Does the mkautodoc API reference get translated?

No. api.md is rendered from Python docstrings by mkautodoc, so a translated copy would still show English docstrings. The agent leaves it as a fallback page and says so; translating the reference means translating the docstrings themselves, which is a different change.

Will the custom theme override break the language switcher?

The site overrides partials/nav.html only, and the switcher lives in Material's header, so it survives. The agent checks it in the browser rather than assuming, because an override of header.html or main.html would need the switcher partial added by hand, and it notes that in the pull request if it applies.

More MkDocs jobs

The same job on other stacks

Keep reading