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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add i18n to a Starlight Docs Site (Starlight)
- Add i18n to a SvelteKit App from a Linear Issue (SvelteKit)
- Add i18n to a Tauri App (Tauri)