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.

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