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.

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.