All jobs

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 RushOpens 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 with this body:

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading