{"record":{"id":"6643a6c209479150","repo":"facebook/docusaurus","slug":"docusaurus-couldn-t-infer-a-default-locale-config","errorCode":null,"errorMessage":"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.","messagePattern":"Docusaurus couldn't infer a default locale config for (.+?)\\.\\\\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\\['(.+?)'\\]\\.htmlLang attribute\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus/src/server/i18n.ts","lineNumber":103,"sourceCode":"export function getDefaultLocaleConfig(\n  // Locale \"key/identifier\"\n  // Can be anything, but usually a country / BCP47 code\n  locale: string,\n  // optionally provided in i18n.localConfigs, need to respect BCP47\n  htmlLang?: string,\n): Omit<I18nLocaleConfig, 'translate' | 'url' | 'baseUrl'> {\n  try {\n    return {\n      label: getDefaultLocaleLabel(htmlLang ?? locale),\n      direction: getDefaultDirection(htmlLang ?? locale),\n      htmlLang: htmlLang ?? locale,\n      calendar: getDefaultCalendar(htmlLang ?? locale),\n      // Fot the i18n/<path>, we don't use htmlLang on purpose\n      // see bug https://github.com/facebook/docusaurus/issues/11952\n      path: locale,\n    };\n  } catch (e) {\n    throw new Error(\n      `Docusaurus couldn't infer a default locale config for ${logger.name(\n        locale,\n      )}.\nMake 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(\n        `siteConfig.i18n.localeConfig['${locale}'].htmlLang`,\n      )} attribute.`,\n      {cause: e},\n    );\n  }\n}\n\nexport function getLocaleList({\n  i18nConfig,\n  currentLocale,\n}: {\n  i18nConfig: I18nConfig;\n  currentLocale: string;\n}): [string, ...string[]] {","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus/src/server/i18n.ts#L85-L121","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a valid BCP 47 locale tag (hyphen-separated, e.g. `'pt-BR'`, `'zh-Hans-CN'`).","Provide an explicit `i18n.localeConfig['<your-locale>'].htmlLang` with a known-good BCP 47 value.","Upgrade Node.js to a version with full `Intl.Locale` info-api support (Node 20+)."],"exampleFix":"// before\ni18n: { defaultLocale: 'fr_FR', locales: ['fr_FR'] },\n// after\ni18n: {\n  defaultLocale: 'fr-FR',\n  locales: ['fr-FR'],\n  localeConfig: { 'fr-FR': { htmlLang: 'fr-FR' } },\n},","handlingStrategy":"validation","validationCode":"function isValidBcp47(locale: string): boolean {\n  try { new Intl.Locale(locale); return true; } catch { return false; }\n}\nif (!isValidBcp47(config.i18n.defaultLocale)) throw new Error('Invalid BCP47 locale');","typeGuard":"function isBcp47Locale(s: string): boolean {\n  try { new Intl.Locale(s); return true; } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["Always use hyphen-separated BCP 47 tags (`fr-FR`, not `fr_FR`).","Provide explicit `localeConfig[locale].htmlLang` for exotic locales.","Use Node 20+ for full `Intl.Locale` info-api coverage."],"tags":["i18n","locale","bcp47","config"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}