docusaurus build "Error: Unable to build website for locale" i18n
Fixes Docusaurus builds that fail with unable-to-build-website for a locale. Use when the error names a specific locale during an i18n build. Not for sidebar or versioning errors.
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
- Open docusaurus.config.js and check the i18n block: the locale must be listed in
localeswith a matching entry inlocaleConfigs. Expected: the failing locale is declared consistently. - 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. - 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.
- 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