# Add a Second Language to a Zola Site

Yes. The agent adds a language to config.toml, moves the theme's hard-coded strings into translations, builds both languages with the pinned Zola and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/zola/). 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 site and its theme are put together before it adds a language, because Zola's multilingual support lives in three places that have to agree: the config, the content file names and the templates. In a site built on getzola/even, `config.toml` sets `base_url`, `title`, `description`, `generate_feed = true`, two taxonomies `categories` and `tags` with feeds, `compile_sass` and `highlight_code`, and under `[extra]` the `even_menu` list of four entries and `even_title`. `theme.toml` pins `min_version = "0.17.0"`, and the deploy workflow in `.github/workflows/docs.yml` builds with `shalzz/zola-deploy-action@v0.17.2`, so the agent builds with Zola 0.17 rather than the newest release. `content/_index.md` sets `paginate_by = 5` and `sort_by = "date"`, each post's front matter carries `[taxonomies]` with `categories` and `tags`, and `content/pages/_index.md` sets `render = false` so `about.md` renders through `templates/about.html`.

The templates are where the English is. `templates/index.html` hard-codes `lang="en"` on the `<html>` element, `Read more...` under each summary, `‹ Previous` and `Next ›` on the paginator, links the feed with `get_url(path=feed)` only when `config.generate_feeds` is set, and renders `config.extra.even_menu` by replacing `$BASE_URL` in each entry's `url` with `config.base_url`. `templates/page.html` has `Contents` over the table of contents and the previous and next post links, `templates/tags/list.html` and `templates/categories/list.html` say `tags in total` and `categories in total`, and `post_macros.html` formats dates with `date(format="%F")`. Zola's templates reference says every template except the feed and sitemap gets a `lang` variable, `trans(key, lang)` reads a key for a given or the active language, and `get_url` takes a `lang` argument that prefixes the path with the language code when it is not the default.

The agent makes the change in that order. In `config.toml` it adds `default_language = "en"`, a `[languages.fr]` table with its own `title`, `description`, `generate_feeds = true` and the same two taxonomies, a top-level `[translations]` table for English and a `[languages.fr.translations]` table for French with keys such as `read_more`, `previous`, `next`, `contents`, `tags_total` and `categories_total`, and a per-language `even_menu`, since the menu's `url` values need the language prefix. In the templates it replaces each literal with `{{ trans(key="read_more", lang=lang) }}`, sets `<html lang="{{ lang }}">`, passes `lang=lang` to `get_url` for the feed and the stylesheet, and switches the menu loop to the current language's entries. It adds `content/_index.fr.md` with the same `paginate_by` and `sort_by`, because a section has no fallback and a translated section needs its own index, translates `content/pages/about.fr.md` and two posts as `first_post.fr.md` and `second_post.fr.md` so the French index is not empty, and adds a language switcher to the header that links each page to its translation when one exists.

Then it builds. It runs `zola check` and `zola build` with the 0.17 binary, lists the `public/fr/` tree to show the French index, the two posts, the taxonomy pages under `public/fr/tags/` and `public/fr/categories/` and the French feed, and greps the output for any remaining English literal from the original templates. It opens a pull request with the config, template and content changes and the build log, and says which posts still have no translation.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add French as a second language to this Zola site. Read config.toml, theme.toml, .github/workflows/docs.yml, content/_index.md, content/pages/_index.md, every file under templates/ and the front matter of the posts first, and read Zola's multilingual and templates documentation for the version the deploy workflow pins. In config.toml add default_language, a [languages.fr] table with its own title, description, feed and the same taxonomies, a [translations] table for English and a [languages.fr.translations] table for French covering every string the templates hard-code, and a per-language menu. Replace each literal in the templates with trans(key=..., lang=lang), set the html lang attribute from lang, and pass lang to get_url for the feed and stylesheet links. Add content/_index.fr.md, translate pages/about.md and two posts as .fr.md files, and add a language switcher to the header that links to a page's translation when it exists. Build with the pinned Zola version, run zola check, show the public/fr tree and confirm no original English literal remains in the templates. Open a pull request with the build log and a list of posts still untranslated. Change nothing else.",
  "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

What comes back is a pull request on its own branch with `config.toml` carrying the language and translation tables, every file under `templates/` with its literals replaced by `trans` calls and `get_url` given `lang`, a new `content/_index.fr.md`, `content/pages/about.fr.md` and two translated posts, and a language switcher in the header. The description quotes the `zola build` summary for both languages, lists the files under `public/fr/`, shows the grep for leftover English literals returning nothing, and names each post that still has only an English version.

The session keeps the record: the documentation pages the agent read, each `zola check` and `zola build` command with its full output, and the directory listings of `public/`. `GET /o/{org}/sessions/{id}/messages` returns that transcript, and `GET /o/{org}/p/{project}/sessions/{id}/changes` returns the diff per file.

Before merging, a reviewer opens `public/fr/` in a browser from the build, clicks the switcher both ways, and reads the French for the strings a machine cannot judge: the menu labels, the pagination words and the `about` page. They check that the English site's URLs did not move, since `default_language` keeps them unprefixed, and that both feeds validate. A follow-up message to the same session, such as translating the remaining posts, continues on the same branch.

## Run it on every site that needs a second language

Start it from your terminal with one `POST /o/{org}/sessions`, this prompt as `input` and the site's repository in `resources`, and read the pull request from the console when it is ready. The key's `webhook_url` receives one `run.completed` with the pull request in `result`. A `request_id` that is a UUID v5 of the repository's full name makes a retried request return the run already started instead of a second pull request.

A team with one site per product sends the same body once per repository, each with the language it needs in the prompt. Each run reads its own theme, so a site on a theme that already uses `trans` gets only the config, content and switcher changes, and the description says which templates it left alone.

## Why run it on Rush?

Adding a language to a Zola site is a long list of small edits spread across the config, every template and the content tree, and the one you miss shows up as English on the French page or a feed link to the wrong path. In a Rush sandbox the agent builds with the exact Zola version the deploy workflow pins, lists what the build produced under `public/fr/` and greps the templates for leftovers, so the pull request shows both languages rendering rather than promising they will.

The pull request carries its proof: the build log, the output tree and the transcript of every command. Several sites can get a language at the same time in separate sandboxes, each against its own theme, and the reviewer's job becomes reading the French rather than hunting for the string that was not translated.

## Frequently asked questions

### Does this change the English URLs?

No. With `default_language = "en"` the English pages keep their paths and only the translated ones gain the `/fr/` prefix, which `get_url(path=..., lang=lang)` produces when `lang` is not the default. The agent checks the English `public/` tree against the build before its change to confirm nothing moved.

### What happens to posts that have no French version?

They stay English and appear only on the English index, since Zola builds each language's section from its own `_index` and the files with that language code. The pull request lists them so a person can translate them later, and a follow-up message to the same session can do it on the same branch.

### Will the theme update break the translations?

If the theme is a git submodule or copied under `themes/`, the agent puts the edited templates in the site's own `templates/` directory, where Zola looks first, so a later theme update does not overwrite them. On a site that is the theme itself, as the example repository is, the templates are edited in place.

### Which Zola version does it build with?

The one the repository pins, read from the deploy workflow or `theme.toml`'s `min_version`, because newer Zola releases reject some older config keys. The agent says in the pull request which version it used, and notes any key the newest release would refuse so you can plan that upgrade separately.

## More Zola jobs

- [Show Last Updated Dates on a Zola Blog](https://getrush.ai/run/add-last-updated-dates/zola/)
- [Add Link Checking to a Zola Site](https://getrush.ai/run/add-link-checking/zola/)
- [Add llms.txt to a Zola Site With a Feed Template](https://getrush.ai/run/add-llms-txt/zola/)

## The same job on other stacks

- [Add i18n to an AdonisJS App](https://getrush.ai/run/add-i18n/adonisjs/)
- [Add i18n to an Angular App](https://getrush.ai/run/add-i18n/angular/)
- [Add a Second Language to an Astro Site](https://getrush.ai/run/add-i18n/astro/)

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