What the agent does
The agent reads the theme and the site before it changes either, because Hugo's multilingual mode touches configuration, templates and content at once. In a site on the Bear Blog theme, as in janraasch/hugo-bearblog's exampleSite, hugo.toml sets theme = 'hugo-bearblog', languageCode = "en-US", disableKinds = ["taxonomy"], a blog = "/:slug/" permalink and a [params] table with description, favicon, images, title and an optional dateFormat; menus are not in the configuration but in front matter, where _index.md, bear.md, hugo.md and blog/_index.md each carry menu = "main" and a weight. The templates hard-code their English: layouts/_default/list.html says Filtering for, Remove filter and No posts yet, layouts/partials/post_navigator.html says Previous Post and Next Post, layouts/partials/footer.html says Made with, and both list.html and single.html format dates with .Date.Format and the default 02 Jan, 2006. baseof.html already sets lang from .Site.Language.Locale, header.html links the title to {{ "" | relURL }}, list.html links the filter reset to {{ "blog" | relURL }}, and nav.html ranges over .Site.Menus.main. theme.toml lists no javascript among the features with min_version = "v0.110.0", and .github/workflows/ci.yml builds the example site with peaceiris/actions-hugo@v3.2.1 and hugo --minify --gc --source ./exampleSite --themesDir ../...
Hugo's multilingual documentation gives the pieces. A second language is a [languages.de] table with its weight, languageName and locale, under a defaultContentLanguage; content is translated by file name, bear.de.md beside bear.md, with the code in lowercase, and the two files are linked as translations of each other; strings move to translation tables, i18n/en.toml and i18n/de.toml, read with {{ T "key" }}, where Hugo looks up the current language's locale, then its key, then the default language's; a missing key falls back to the default language, enableMissingTranslationPlaceholders makes gaps visible, and hugo build --printI18nWarnings lists them. Dates localise through time.Format, which renders month and day names in the page's language. Menu entries defined in front matter are localised by that front matter, so each translated file keeps its own menu and weight and no menu configuration is needed. For a theme, URLs built from strings must go through relLangURL or carry .LanguagePrefix, which is empty on a single-language site and so harmless there.
The agent adds i18n/en.toml to the theme with keys for every string it found, filteringFor, removeFilter, noPostsYet, previousPost, nextPost and madeWith, and a de.toml with the German, then replaces each string in list.html, post_navigator.html and footer.html with T. Both date lines become {{ .Date | time.Format (default "02 Jan, 2006" .Site.Params.dateFormat) }}, so a site's own dateFormat still applies and month names follow the language. header.html links the title to .Site.Home.RelPermalink, which is the language's home, and list.html builds its reset link with relLangURL. A new partials/language_switcher.html, included from header.html only when hugo.IsMultilingual is true, lists .Translations of the current page when it has any and otherwise the home page of each other language from .Site.Home.AllTranslations, as plain links with no script, so the theme's promise holds. In exampleSite/hugo.toml it adds defaultContentLanguage = "en" with [languages.en] and [languages.de], each with languageName, locale, weight and its own title and params.description, and translates three content files, _index.de.md, bear.de.md and blog/_index.de.md, leaving the Markdown syntax post untranslated on purpose so the switcher's fallback is exercised.
Then the agent builds every language. It installs the current Hugo release, v0.169.0 when read, runs the CI command from ci.yml with --printI18nWarnings added, and checks public/index.html and public/de/index.html both exist, that the German page carries lang="de-DE", the translated strings and a German month name in a post date, that the English site is byte-for-byte what it was apart from the switcher, and that no MISSING_TRANSLATION line names a key the tables should have. It runs the theme's npm run beautify so the edited templates match the repository's formatting, and adds a README section on adding a language: the [languages] table, the .de.md file naming, and the i18n/ key list.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add multilingual support to this Hugo theme and its example site. Read theme.toml, every file under layouts/, exampleSite/hugo.toml, every file under exampleSite/content/, the README and .github/workflows/ci.yml first. Move every hard-coded string in the templates into i18n/en.toml with a matching i18n/de.toml and render them with T. Format dates with time.Format so month names follow the language, keeping the site's dateFormat param. Make string-built URLs language-aware with relLangURL and the home link with .Site.Home.RelPermalink. Add a language switcher partial with no JavaScript, shown only when the site is multilingual, that lists the page's translations or falls back to each language's home. In exampleSite/hugo.toml add defaultContentLanguage and a languages table for en and de, and translate the home page, one page and the blog section index by file name. Install Hugo, build the example site with the CI command plus --printI18nWarnings, confirm both languages render and no translation is missing, run the repository's beautify script, and add a README section on adding a language. Open a pull request with the commands and their output.",
"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 i18n/en.toml, i18n/de.toml and layouts/partials/language_switcher.html, changes list.html, single.html, header.html, footer.html and post_navigator.html, adds the three .de.md files and the [languages] tables to exampleSite/hugo.toml, and extends the README. Its description quotes the build summary per language, the --printI18nWarnings output, and the rendered German date and switcher markup from public/de/, so a reviewer sees the second language without building.
A reviewer checks the German strings, whether the switcher belongs in the header or the footer, whether defaultContentLanguageInSubdir should put English under /en/ too, which the pull request leaves off so existing English URLs do not move, and whether the untranslated post should fall back to English content with lang.Merge or stay absent from the German site. A site using the theme as a submodule gets the same change by updating the submodule and adding its own [languages] table and .de.md files.
Run it on every Linear issue labelled i18n
An automation in the Project that holds the site takes a linear trigger on linear.issue.labeled with the label i18n. Its runs are read-only, so the saved prompt asks for a plan: the run reads the templates, lists every hard-coded string and every URL built from a string, and posts a comment on the issue with the keys it would add, the files it would translate for the language the issue names, and the configuration lines. A handler on the team's server starts the run that writes the pull request, sending this body with the issue's URL in resources and a request_id that is a UUID v5 of the issue id, so a retried start returns the run already started.
A later issue for a third language runs the same way and touches only i18n/, the configuration and the content files, because the templates already read every string through T.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Whether a multilingual site is right is only visible in the built output: a date in the wrong language, a link that drops the language prefix, a string that fell back to English because its key was misspelt. The agent installs Hugo, builds every language in its own sandbox with the warnings flag on, reads the generated HTML for each and keeps every command and its output in the run's record, so the pull request shows a German page that exists rather than templates that should produce one.
The change is fitted to this theme and site: strings are found by reading the templates rather than a list, menus stay in front matter because that is where this site keeps them, and the switcher adds no script because theme.toml promises none. Ten sites on ten themes get ten pull requests, each with its own key list and its own translated files.
Frequently asked questions
Will my existing URLs change?
No. The default language stays at the root and only the new language gets a prefix, /de/ here, because defaultContentLanguageInSubdir is left off. The pull request says where that one line goes if you want every language under its own prefix.
Do I have to translate every page?
No. A page with no translation is simply absent from the other language's site and its list pages, and the switcher falls back to that language's home. Hugo's lang.Merge can fill the gap with the default language's content instead, and the pull request names it as the alternative.
Where do the menu translations come from?
From the translated files themselves. This site defines its menu in front matter, so bear.de.md carries its own menu and weight and its own title, and Hugo builds a German menu from them. Sites that define menus in hugo.toml need a menu table per language instead, which the README section covers.
Why go through time.Format rather than the existing Date.Format?
Because time.Format renders month and day names in the current language while .Date.Format always uses English. The layout string is unchanged and the site's dateFormat param still applies, so the English site renders exactly as before.
Does the switcher add JavaScript?
No. It is a partial of plain links built from the page's translations, included only when the site has more than one language, so a single-language site using the theme renders nothing new and the theme keeps the no javascript feature it lists in theme.toml.