facebook/docusaurus · error · Error

Docusaurus couldn't infer a default locale config for ${loca

Error message

Docusaurus couldn't infer a default locale config for ${locale}.\nMake sure it is a valid BCP 47 locale name (e.g. en, fr, fr-FR, etc.) and/or provide a valid BCP 47 siteConfig.i18n.localeConfig['${locale}'].htmlLang attribute.

What it means

Thrown by `getDefaultLocaleConfig` when Docusaurus cannot derive a default locale (label, text direction, calendar) from the configured locale string. Internally it constructs an `Intl.Locale`, whose getters throw on malformed input; the catch at i18n.ts:102-112 re-wraps that into a user-facing message with the offending locale and a hint about `localeConfig[locale].htmlLang`.

Source

Thrown at packages/docusaurus/src/server/i18n.ts:103

export function getDefaultLocaleConfig(
  // Locale "key/identifier"
  // Can be anything, but usually a country / BCP47 code
  locale: string,
  // optionally provided in i18n.localConfigs, need to respect BCP47
  htmlLang?: string,
): Omit<I18nLocaleConfig, 'translate' | 'url' | 'baseUrl'> {
  try {
    return {
      label: getDefaultLocaleLabel(htmlLang ?? locale),
      direction: getDefaultDirection(htmlLang ?? locale),
      htmlLang: htmlLang ?? locale,
      calendar: getDefaultCalendar(htmlLang ?? locale),
      // Fot the i18n/<path>, we don't use htmlLang on purpose
      // see bug https://github.com/facebook/docusaurus/issues/11952
      path: locale,
    };
  } catch (e) {
    throw new Error(
      `Docusaurus couldn't infer a default locale config for ${logger.name(
        locale,
      )}.
Make sure it is a valid BCP 47 locale name (e.g. en, fr, fr-FR, etc.) and/or provide a valid BCP 47 ${logger.code(
        `siteConfig.i18n.localeConfig['${locale}'].htmlLang`,
      )} attribute.`,
      {cause: e},
    );
  }
}

export function getLocaleList({
  i18nConfig,
  currentLocale,
}: {
  i18nConfig: I18nConfig;
  currentLocale: string;
}): [string, ...string[]] {

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Use a valid BCP 47 locale tag (hyphen-separated, e.g. `'pt-BR'`, `'zh-Hans-CN'`).
2. Provide an explicit `i18n.localeConfig['<your-locale>'].htmlLang` with a known-good BCP 47 value.
3. Upgrade Node.js to a version with full `Intl.Locale` info-api support (Node 20+).

Example fix

// before
i18n: { defaultLocale: 'fr_FR', locales: ['fr_FR'] },
// after
i18n: {
  defaultLocale: 'fr-FR',
  locales: ['fr-FR'],
  localeConfig: { 'fr-FR': { htmlLang: 'fr-FR' } },
},

function isValidBcp47(locale: string): boolean {
  try { new Intl.Locale(locale); return true; } catch { return false; }
}
if (!isValidBcp47(config.i18n.defaultLocale)) throw new Error('Invalid BCP47 locale');

function isBcp47Locale(s: string): boolean {
  try { new Intl.Locale(s); return true; } catch { return false; }
}

When it happens

Trigger: Setting `i18n: { defaultLocale: 'xx-YY' }` (or any non-BCP47 string), where `new Intl.Locale(...)` or `locale.getTextInfo()`/`locale.getCalendars()` throws. The cause chain preserves the original RangeError.

Common situations: Typos in locale codes (`'fr_FR'` instead of `'fr-FR'`); using a non-standard language tag; Node.js version differences in `Intl.Locale` support; forgetting to provide `localeConfig` overrides for an exotic locale.

Related errors

• Can't find locale config for locale ${logger.code(localeToLo
• No tags file '${relativeFilePath}' could be found in any of
• Can't write-translation for locale "${locale}" that is not i
• Translation file path at "${translationFilePath}" does not n
• Localized config key=${key} not found

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/6643a6c209479150. Report an issue: GitHub.