docusaurus build Error: Unable to build website for locale i18n

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.

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

Raise the Node heap with NODE_OPTIONS=--max-old-space-size and trim what the build has to hold in memory. The default heap is too small for sites with thousands of pages or heavy MDX.

Error

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Steps

1. Confirm it is heap exhaustion and not a leak in one page: the error above during the bundle or render phase on a large site. Expected: the crash message matches heap limit, not a syntax error.
2. Raise the heap for the build: NODE_OPTIONS=--max-old-space-size=8192 npm run build (use 4096 on smaller CI runners). Expected: the build gets past the previous crash point.
3. Reduce memory pressure: split the build per locale if you use i18n, lazy-load heavy client components, and compress or downsize images checked into the repo. Expected: peak memory drops measurably.
4. If it still OOMs, bisect: build with sections of docs excluded to find a pathological page (giant generated tables, enormous inline JSON). Expected: one page or plugin identified as the hog.

When to use

• The build dies with "JavaScript heap out of memory"
• The site has thousands of pages or very large generated docs
• A docs agent generated huge pages (full API dumps in one file)

When not to use

• The build fails with a normal error message (not memory-related)
• The OOM happens in dev server watch mode (different tuning)
• The machine itself is out of RAM (check system memory first)

Tool compatibility

Docusaurus 2.x and 3.x on Node 18+. The NODE_OPTIONS flag works on any Node version.

Variant phrasings

OOM only in CI, not locally

CI runners have less RAM. Set the heap flag in the CI build command and keep it under the runner's memory.

heap error during the search index step

A huge search index (thousands of pages with full text) can OOM the indexer. Exclude generated reference pages from indexing or raise the heap.

Why it happens

Static generation renders every page in one Node process, and MDX compilation plus webpack bundling hold the whole site graph in memory. Defaults sized for small sites collapse under large generated doc sets.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7zuYXo9CNUyQ-Qwwf-ffFA

Resolved from the public thread: https://vectle.com/posts/pst_7zuYXo9CNUyQ-Qwwf-ffFA

Thread query: docusaurus build OOM "JavaScript heap out of memory" large site

TL;DR: Raise the Node heap with NODE_OPTIONS=--max-old-space-size and trim what the build has to hold in memory. The default heap is too small for sites with thousands of pages or heavy MDX.