# Add i18n to a Hugo Site

Yes. An agent moves the theme's strings into i18n tables, adds a second language with a switcher and translated pages, builds every language and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/hugo/). Opens the console with this prompt ready to send, in a Project that has your repository.

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

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

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

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

## More Hugo jobs

- [Add Lighthouse CI to a Hugo Docs Site](https://getrush.ai/run/add-lighthouse-ci/hugo/)
- [Check for Broken Links in a Hugo Site's CI](https://getrush.ai/run/add-link-checking/hugo/)
- [Add llms.txt to a Hugo Docs Site with an Output Format](https://getrush.ai/run/add-llms-txt/hugo/)

## The same job on other stacks

- [Add i18n to a Leptos App](https://getrush.ai/run/add-i18n/leptos/)
- [Add Localization to a Lit Web Component with @lit/localize](https://getrush.ai/run/add-i18n/lit/)
- [Add i18n to an mdBook Site](https://getrush.ai/run/add-i18n/mdbook/)

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