# Add i18n to an mdBook Site

Yes. An agent adds mdbook-i18n-helpers to your book: the gettext preprocessor, a po/ template, a per-language build in CI, a translators' guide, and a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/mdbook/). 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 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`

```json
{
  "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"
    }
  ]
}
```

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

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

- [Add Last Updated Dates to an mdBook Site](https://getrush.ai/run/add-last-updated-dates/mdbook/)
- [Add External Link Checking to an mdBook](https://getrush.ai/run/add-link-checking/mdbook/)
- [Add llms.txt to an mdBook Site](https://getrush.ai/run/add-llms-txt/mdbook/)

## The same job on other stacks

- [Add i18n to a MkDocs Site](https://getrush.ai/run/add-i18n/mkdocs/)
- [Add i18n to an Obsidian Plugin](https://getrush.ai/run/add-i18n/obsidian-plugin/)
- [Add i18n with Gettext to a Phoenix LiveView App from a Linear Issue](https://getrush.ai/run/add-i18n/phoenix-liveview/)

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