What the agent does
The agent reads how the book is built and published before it changes the toolchain. In a book laid out like rust-embedded/book, book.toml is seven lines: a [book] table with authors, src = "src" and title, and an [output.html] table with git-repository-url. src/SUMMARY.md lists the chapters, forty-four Markdown files, with images under src/assets. .github/workflows/ci.yml runs on every push, pull request and merge group: it installs a stable Rust toolchain with dtolnay/rust-toolchain, installs linkchecker with pip, restores a ~/cargo-bin cache or installs the latest mdbook with actions-rs/install and copies the binary there, then runs mdbook build, mdbook test and linkchecker book, and on a push to master deploys the book directory to the gh-pages branch with peaceiris/actions-gh-pages and force_orphan: true. .gitattributes normalises every text file to LF. There is no po/ directory, no theme/ override and no translation guide, and README.md says the prose is licensed CC-BY-SA, which is what a translation inherits.
The toolchain is mdbook-i18n-helpers, installed with cargo install mdbook-i18n-helpers --locked, which provides mdbook-xgettext, mdbook-gettext and mdbook-i18n-normalize. book.toml gains a [preprocessor.gettext] table with after = ["links"], so included files are translated as part of the page they land in, and optional = true, so a contributor without the binary still gets a plain English build with a warning instead of an error; and a [build] table with extra-watch-dirs = ["po"] so mdbook serve reloads when a translation changes. The agent then runs MDBOOK_OUTPUT='{"xgettext": {}}' mdbook build -d po, which writes po/messages.pot: one msgid per paragraph, heading and list item with a comment naming the source file and line, and it reads that file to confirm the chapters came through in SUMMARY.md order.
The workflow learns to build every language that has a translation. After mdbook build, a step installs the helpers into the same ~/cargo-bin the workflow already caches, then loops over po/*.po, takes each file's name as the language, and runs MDBOOK_BOOK__LANGUAGE=<lang> mdbook build -d book/<lang>. Because those directories sit inside book, the existing linkchecker book step checks them and the existing deploy step publishes them at /book/<lang>/ with no change to either. mdbook test keeps running on the English source only, since translated code blocks would be tested twice for no gain. A TRANSLATING.md at the root gives translators the four commands they need: msginit -i po/messages.pot -l <lang> -o po/<lang>.po to start a language, msgmerge --update po/<lang>.po po/messages.pot after the English changes, MDBOOK_BOOK__LANGUAGE=<lang> mdbook serve to read their work, and mdbook-i18n-normalize after upgrading the helpers.
The agent proves the pipeline before it commits it. In its sandbox it installs the gettext package for msginit and msgmerge, creates a throwaway po/de.po, translates the introduction's first two paragraphs, and builds with MDBOOK_BOOK__LANGUAGE=de mdbook build -d book/de: book/de/intro/index.html shows the translated paragraphs and the untranslated ones fall back to English, which is the behaviour translators will rely on. It runs mdbook build, mdbook test and linkchecker book the way the workflow does, deletes the throwaway file so the pull request ships only the template, and runs the modified workflow's shell loop locally to check it handles an empty po/ directory without failing.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add translation support to this mdBook with mdbook-i18n-helpers and open a pull request. Read book.toml, src/SUMMARY.md, .github/workflows/ci.yml, .gitattributes and README.md first. Install mdbook-i18n-helpers with cargo install --locked. Add [preprocessor.gettext] with after = [\"links\"] and optional = true, and [build] extra-watch-dirs = [\"po\"] to book.toml. Generate po/messages.pot with MDBOOK_OUTPUT='{\"xgettext\": {}}' mdbook build -d po and commit it. In the CI workflow, after the English build, install the helpers into the cached binary directory and build every po/*.po language with MDBOOK_BOOK__LANGUAGE into book/<lang> so the link check and the gh-pages deploy cover them; keep mdbook test on the English source. Write TRANSLATING.md with the msginit, msgmerge, serve and normalize commands and the license note for translations. Prove it in the sandbox with a temporary translation that you do not commit, run mdbook build, mdbook test and linkchecker, then open a pull request describing the pipeline and how a translator adds a language.",
"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 adds po/messages.pot and TRANSLATING.md, changes book.toml and .github/workflows/ci.yml, and adds a line to README.md pointing translators at the guide. Its description explains the two book.toml tables, shows the workflow loop, and quotes the sandbox build of the temporary language with the fallback behaviour visible, so a reviewer sees that an incomplete translation publishes as a mixed page rather than a broken one.
It is explicit about what the English site does not do: with no language set the preprocessor passes every chapter through unchanged, so the published book at its current URL is byte-for-byte what it was, and the optional = true setting means a contributor's local mdbook build without the helpers installed prints a warning and succeeds.
Before merging, a reviewer decides whether to pin mdbook and the helpers to versions in the workflow instead of latest, since a new mdBook release can change what mdbook-xgettext extracts, and who will own the po/ directory, since every English edit now implies a msgmerge for each language.
Run it on every Monday morning
Once translations exist, a scheduled automation on the Project, weekly, with the prompt "regenerate po/messages.pot, run msgmerge --update on every po/*.po, and open a pull request that lists, per language, how many entries are new and how many are now fuzzy" starts one run a week. The run reads the repository at that moment, so a week with no English edits produces a pull request with nothing but a refreshed template, and the prompt tells it to open none in that case.
A publisher with several mdBook titles sends this body once per repository from its own server, each 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. A book that already has a po/ directory from an earlier attempt gets its template regenerated and its workflow fixed rather than a second setup.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Translation tooling touches the build, the deploy and the contributor workflow at once, and the failure modes are quiet: a preprocessor that errors for anyone without the binary, a deploy that publishes the English book under every language path, a template extracted before the links preprocessor so included files vanish from it. The agent sets each of those up from the helpers' own conventions and proves them in a sandbox with Rust, mdBook, gettext and linkchecker installed, which is more than most contributors have on their laptop.
The template, the throwaway translation's rendered page, the test run and the link check stay with the run, so the reviewer reads evidence instead of trusting a description. A publisher with several books sends the same request to all of them and gets one pull request per book, each proved on its own content.
Frequently asked questions
Does this translate the book?
No. It produces po/messages.pot, the template every translation starts from, and the build and publish path for any po/<lang>.po that is added later. Translating is a human job; the pull request gives translators the commands and the fallback behaviour they can rely on while a language is incomplete.
What happens to code blocks?
Code blocks are extracted into the template like any other block, and a translator who leaves an entry untranslated gets the original in the built page. mdbook test keeps running on the English source only, so a translated comment inside a code block can never break the test step.
Will the English site change?
No. With MDBOOK_BOOK__LANGUAGE unset the gettext preprocessor passes every chapter through untouched, and the workflow's first mdbook build is the same command as before. The translations land beside it under book/<lang>/ and share the one deploy.
How does a translator add a language?
With msginit -i po/messages.pot -l fr -o po/fr.po, then edits in any PO editor, then MDBOOK_BOOK__LANGUAGE=fr mdbook serve to read the result. TRANSLATING.md carries those commands, the msgmerge --update step for keeping up with English edits, and the note that fuzzy entries render as English until the flag is cleared.
More mdBook jobs
The same job on other stacks
- Add i18n to a MkDocs Site (MkDocs)
- Add i18n to an Obsidian Plugin (Obsidian plugin)
- Add i18n with Gettext to a Phoenix LiveView App from a Linear Issue (Phoenix LiveView)