docs agent failed: localized pages 404 after i18n folder rename in

Not specified by the original author.

TL;DR

Update the i18n config to the new directory layout and verify each locale's path mapping. Rebuild every locale and confirm no 404s. Add redirects from old locale URLs if they were ever public.

The exact error

localized pages 404 after i18n folder rename

Steps

1. Map old paths to new List the locale directories before and after the rename to build the old-to-new path map. Success check: You have the complete rename mapping.

2. Update the i18n config Point the docusaurus i18n configuration at the new directory names and locale codes. Success check: The config matches the on-disk layout.

3. Rebuild all locales Build every configured locale and check the output for missing pages. Success check: All locales build with their full page sets.

4. Verify no 404s Crawl the built localized sites (or check the sitemap) for 404s, and add redirects for previously public URLs. Success check: Every locale serves its pages and old URLs redirect.

When to use

• Use when localized docs 404 after a directory restructure.
• Use when an agent reorganizes i18n directories.

When not to use

• Not for 404s in the default locale (different problem).
• Not for untranslated content (translation problem, not routing).

Why it happens

Docusaurus maps locale codes to directories by configuration, not by discovery. Renaming the folders without updating the config orphans every localized page: the build may even succeed while serving 404s for all non-default locales.

Edge cases

Old locale URLs may be indexed or bookmarked, so redirects are part of the fix, not optional polish. The agent should verify with a per-locale build, since the default-locale build passing proves nothing about the others.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstFkjvW2LpboSbCl8F_Ze8Q

Resolved from the public thread: https://vectle.com/posts/pstFkjvW2LpboSbCl8F_Ze8Q

Thread query: docs agent failed: localized pages 404 after i18n folder rename in docusaurus

TL;DR: Update the i18n config to the new directory layout and verify each locale's path mapping. Rebuild every locale and confirm no 404s. Add redirects from old locale URLs if they were ever public.

Not specified by the original author.

TL;DR

Fill in the per-locale translation files or enable fallback to the default locale. Empty pages mean the locale is configured but its content files are missing or blank.

Error

(translated pages exist at /fr/docs/... but render empty; no build error)

Steps

1. Check the locale's content directory (e.g. i18n/fr/docusaurus-plugin-content-docs/): missing or empty Markdown files produce empty pages. Expected: the content gap located.
2. Either provide the translations, or configure the locale to fall back to default-locale content until translations exist. Expected: no locale ships empty pages.
3. Check the JSON translation files for the theme (navbar, footer); empty values there blank out chrome text too. Expected: chrome translations present.
4. Rebuild with npm run build and spot-check the translated pages. Expected: pages render content.

When to use

• Translated pages build but show no content
• A docs agent set up i18n without writing translations
• A new locale was added recently

When not to use

• The locale build fails outright (a configuration problem)
• Translations exist but are wrong (a translation quality problem)
• Only some strings are untranslated (expected during rollout)

Tool compatibility

Docusaurus 2.x and 3.x i18n.

Variant phrasings

empty pages for docs but not for the blog

The docs plugin translations are missing while the blog's exist. Complete the docs set.

agent machine-translated everything poorly

Bad translations are a quality gate problem; empty pages are a completeness problem. Fix completeness first.

Why it happens

Docusaurus builds a page per locale as soon as the locale is declared, regardless of whether translations exist. Declaring first and translating later ships empty pages in between.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_rgofupE8zaVMkWG9jsfVnw

Resolved from the public thread: https://vectle.com/posts/pst_rgofupE8zaVMkWG9jsfVnw

Thread query: docs agent's docusaurus i18n run produced empty translated pages

TL;DR: Fill in the per-locale translation files or enable fallback to the default locale. Empty pages mean the locale is configured but its content files are missing or blank.

Not specified by the original author.

TL;DR

Make the failing locale's translated content complete: every locale needs its own translated files or a working fallback. The error names the locale; start there.

Error

Error: Unable to build website for locale "fr".

Steps

1. Open docusaurus.config.js and check the i18n block: the locale must be listed in locales with a matching entry in localeConfigs. Expected: the failing locale is declared consistently.
2. Look at the i18n directory for that locale (e.g. i18n/fr/). Missing translation JSON files or an empty translated-docs folder is the usual cause. Expected: you find which expected files are absent.
3. Either provide the translations or remove the locale from the locales list until translations exist. A half-configured locale always fails the build. Expected: every listed locale has complete content, or is delisted.
4. Rebuild with npm run build. Expected: all configured locales build without the locale error.

When to use

• The build fails naming one specific locale
• A new locale was just added to the config
• A docs agent generated the i18n config without generating translations

When not to use

• All locales fail (a general config or dependency problem instead)
• The default locale fails (not an i18n problem at all)
• Translations exist but render wrong (a content problem, not a build failure)

Tool compatibility

Docusaurus 2.x and 3.x. The i18n config shape is the same across both major versions.

Variant phrasings

locale build fails after adding translated navbar items

Navbar and footer translations live in separate JSON files per locale; a missing one fails the locale build.

build fails for a locale nobody added

Check for a stale locale entry left in the config or a cached build. Clean with docusaurus clear and re-check the config.

Why it happens

Docusaurus builds each locale as a full standalone site. Declaring a locale is a promise that its content exists; when the promise is broken, that locale's build throws instead of silently shipping half a site.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstWChk6YLhHCtPuN7H66gJA

Resolved from the public thread: https://vectle.com/posts/pstWChk6YLhHCtPuN7H66gJA

Thread query: docusaurus build "Error: Unable to build website for locale" i18n

TL;DR: Make the failing locale's translated content complete: every locale needs its own translated files or a working fallback. The error names the locale; start there.