# Add i18n to a Sphinx Docs Site

Yes. An agent sets up gettext translation for your Sphinx docs with sphinx-intl, extracts the catalogs, adds a translated build to tox and CI, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/sphinx/). 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 docs are built before it adds a language, since a translated build has to run through the same strict build the English one does. In a project laid out like pallets/click, `docs/conf.py` names the `click` theme from `pallets-sphinx-themes`, enables `sphinx.ext.autodoc`, `sphinx.ext.intersphinx`, `sphinx_tabs.tabs`, `sphinxcontrib.log_cabinet` and `myst_parser` with `myst_heading_anchors` at 3, and reads the version from the installed package with `get_version`. The sources are Markdown: 40 `.md` files under `docs/` from `quickstart.md` to `shell-completion.md`, with `index.md` as `master_doc`. `pyproject.toml` keeps the docs dependencies in a `docs` dependency group (`myst-parser`, `pallets-sphinx-themes`, `sphinx`, `sphinx-tabs`, `sphinxcontrib-log-cabinet`) resolved by `uv.lock`, and a `[tool.tox.env.docs]` environment runs `sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml`, so any warning fails the build. `.readthedocs.yaml` installs `uv` and runs `uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html`. There is no `locale_dirs`, no `language`, no `.pot` or `.po` file anywhere, and `.github/workflows/tests.yaml` skips `docs/**` entirely.

It adds `sphinx-intl` to the `docs` group in `pyproject.toml` and refreshes `uv.lock` with `uv lock`, then sets `locale_dirs = ["locale/"]` and `gettext_compact = False` in `conf.py`, so each source document gets its own catalog instead of one file per directory, which keeps a translator's diff readable across 40 pages. It runs `sphinx-build -b gettext docs docs/_build/gettext` to extract every paragraph, heading, table cell and docstring that `autodoc` pulls from the package into `.pot` templates, then `sphinx-intl update -p docs/_build/gettext -l de` (or whichever locales the prompt names), which writes `docs/locale/de/LC_MESSAGES/<document>.po` with every message as `msgid` and an empty `msgstr`. Those `.po` files are what a translator or a translation platform edits; the agent commits them untranslated except for the handful of strings the prompt asks it to fill, such as the index page's heading, so the pipeline is visible end to end.

The build then has to prove the language works under `-W`. The agent adds a `docs-de` tox environment beside `docs` that runs the same `sphinx-build` with `-D language=de` into `docs/_build/dirhtml-de`, which also compiles each `.po` to `.mo` as Sphinx has done since 1.3, so no separate `sphinx-intl build` step is needed. It adds a `docs.yaml` workflow that runs the `docs` and `docs-de` environments on pull requests that touch `docs/**`, closing the gap `tests.yaml` leaves with its `paths-ignore`, and a `gettext` check in the same workflow that re-extracts the catalogs and fails if `git diff --exit-code docs/locale` shows a `.pot` or `.po` changed, so a documentation edit that forgets `sphinx-intl update` is caught. A `README` paragraph under `docs/` tells contributors the two commands to run after editing a page.

Two details of this project need care, and the agent handles them explicitly. `autodoc` messages come from the package's docstrings, so the catalogs contain API text that changes with the code, and the workflow's drift check keeps them current rather than letting them rot. And `myst_parser` extracts Markdown the same way reST is extracted, but a MyST attribute block such as `{#anchor}` on a heading must survive translation, so the agent documents in the `.po` headers that anchors stay as written. In its sandbox it runs `uv sync --group docs`, both tox environments and the drift check, and opens the pull request with the German `index` page rendered from the few translated strings as evidence.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Set up translations for the Sphinx documentation in this repository, with German as the first target language. Read pyproject.toml, uv.lock's header, docs/conf.py, docs/index.md, .readthedocs.yaml, the tox docs environment and .github/workflows first. Add sphinx-intl to the docs dependency group and update the lockfile with uv lock. Set locale_dirs and gettext_compact in conf.py, extract the catalogs with the gettext builder, run sphinx-intl update for de, and commit the .po files with only the index page's title and first paragraph translated. Add a docs-de tox environment that builds with -W and -D language=de, a workflow that runs the docs and docs-de environments on pull requests touching docs/ and fails if re-extracting the catalogs changes any file under docs/locale, and a short contributor note on the two commands to run after editing a page. Run uv sync, both environments and the drift check, and open a pull request. Do not change any English page or the Read the Docs configuration.",
  "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 edits `pyproject.toml`, `uv.lock` and `docs/conf.py`, adds `docs/locale/de/LC_MESSAGES/` with one `.po` per source document, the `docs-de` environment under `[tool.tox.env]`, `.github/workflows/docs.yaml` and a contributor note. Its description pastes both `sphinx-build` runs ending without warnings, the drift check passing, a count of messages per catalog, and a screenshot of the German index page with its translated heading above untranslated English body text, which is how a partially translated Sphinx site renders.

A reviewer decides which locales to add next with the same `sphinx-intl update -l` call, whether the catalogs go to a translation platform (Weblate and Crowdin both read `.po` files from `docs/locale`) or stay in the repository, and whether Read the Docs should get a `de` translation project pointed at the same repository, which is a dashboard setting the pull request describes but does not make.

## Run it on every new language request

A maintainer who gets a translation offer as a GitHub issue adds an automation to the Project with a `github` trigger on `issues.labeled` and the label `i18n`, and this prompt. The trigger appends the issue after the prompt, so the agent reads the language from the issue ("Japanese docs" runs `sphinx-intl update -l ja` and adds a `docs-ja` environment) while the prompt text stays fixed. Only an issue labelled by an owner, member or collaborator fires it, and the automation runs at most `max_runs_per_hour` times 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 `conf.py`: a project with reST sources gets the same catalogs from the same builder, and one that already has `locale_dirs` gets only the new language and the drift check.

## Why run it on Rush?

Sphinx translation setup is a sequence of commands whose order matters, extracting before updating, updating before building, and a strict build that fails on the first mistranslated role or missing anchor. On a laptop the first attempt usually ends with a `.po` file that the next docs edit silently invalidates. In its sandbox the agent runs the extraction, the update and both strict builds, and leaves the drift check behind so the catalogs cannot go stale unnoticed.

The run keeps every command and its output, from `uv lock` to the per-catalog message counts, so a reviewer can see exactly what was extracted and why a file exists. The same request runs across every documentation site a team keeps at once.

## Frequently asked questions

### Does the agent translate the whole documentation?

No. It extracts every message into `.po` files and translates only the index page's title and first paragraph, so the pipeline can be seen working. The rest of each catalog is empty `msgstr` entries for a translator, or a translation platform that reads `.po` files, to fill; an untranslated message renders in English.

### Why gettext_compact = False?

With the default, Sphinx merges every document in a directory into one catalog, which for 40 pages in one `docs/` directory is a single enormous `.po` file. Setting it to `False` gives one catalog per document, so a change to `quickstart.md` touches `quickstart.po` alone and translators can work page by page.

### What happens when an English page changes?

The affected messages change, and the `.po` entries for them become stale. The workflow re-extracts the catalogs on every docs pull request and fails if `docs/locale` differs, so the author runs the two commands from the contributor note, `sphinx-build -b gettext` then `sphinx-intl update`, and commits the refreshed files with the page.

### Will the German build fail on untranslated text?

No. A message with an empty `msgstr` falls back to the source text, and that is not a warning. What `-W` does catch is a translation that breaks markup, such as a MyST role or an anchor rewritten inside the translated string, which is why the translated build runs under the same flag as the English one.

### Do the API docstrings get translated too?

They are extracted. `autodoc` pulls docstrings from the installed package into the pages, and the gettext builder sees them like any paragraph, so each appears in the catalog for the page that documents it. Whether to translate API text is a project decision; leaving those entries empty keeps the docstrings in English.

## More Sphinx jobs

- [Add Last Updated Dates to Sphinx Docs](https://getrush.ai/run/add-last-updated-dates/sphinx/)
- [Check for Broken Links in Sphinx Docs with the linkcheck Builder](https://getrush.ai/run/add-link-checking/sphinx/)
- [Add llms.txt to a Sphinx Docs Site](https://getrush.ai/run/add-llms-txt/sphinx/)

## The same job on other stacks

- [Add i18n to a Starlight Docs Site](https://getrush.ai/run/add-i18n/starlight/)
- [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/)

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