{"record":{"id":"0944f02f357c6eb3","repo":"GoogleChrome/lighthouse","slug":"unsupported-locale-locale","errorCode":null,"errorMessage":"Unsupported locale '${locale}'","messagePattern":"Unsupported locale '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"shared/localization/format.js","lineNumber":417,"sourceCode":"\n/**\n * Returns the locale messages for the given `locale`, if they exist.\n * Throws if an unsupported locale.\n *\n * NOTE: If DEFAULT_LOCALE is requested and this is inside a bundle with locale\n * messages stripped, an empty object will be returned. Default fallbacks will need to handle that case.\n * @param {LH.Locale} locale\n * @return {import('./locales').LhlMessages}\n */\nfunction _getLocaleMessages(locale) {\n  const localeMessages = LOCALE_MESSAGES[locale];\n  if (!localeMessages) {\n    if (locale === DEFAULT_LOCALE) {\n      // If the default locale isn't in LOCALE_MESSAGES, this is likely executing\n      // in a bundle. Let the caller use the fallbacks available.\n      return {};\n    }\n    throw new Error(`Unsupported locale '${locale}'`);\n  }\n\n  return localeMessages;\n}\n\n/**\n * Returns whether the `requestedLocale` is registered and available for use\n * @param {LH.Locale} requestedLocale\n * @return {boolean}\n */\nfunction hasLocale(requestedLocale) {\n  // The default locale is always supported through `IcuMessage.formattedDefault`.\n  if (requestedLocale === DEFAULT_LOCALE) return true;\n\n  const hasIntlSupport = Intl.NumberFormat.supportedLocalesOf([requestedLocale]).length > 0;\n  const hasMessages = Boolean(LOCALE_MESSAGES[requestedLocale]);\n\n  return hasIntlSupport && hasMessages;","sourceCodeStart":399,"sourceCodeEnd":435,"githubUrl":"https://github.com/GoogleChrome/lighthouse/blob/9515cd4e58ebed69f78742d932b501c2cab8ad8f/shared/localization/format.js#L399-L435","documentation":"Thrown by the internal _getLocaleMessages in the i18n format module when a locale is requested that has no registered messages (not present in LOCALE_MESSAGES) and is not the DEFAULT_LOCALE. Locales must be registered ahead of time via registerLocaleData. The default-locale case is special-cased so a stripped bundle returns {} instead of throwing.","triggerScenarios":"Any i18n formatting call (e.g. format) that resolves to _getLocaleMessages for a locale whose messages were never registered with format.registerLocaleData, in a context where the locale is also not the default.","commonSituations":"A bundle build that stripped non-default locale message JSON; calling format with a locale string that is not a supported LH.Locale; forgetting to registerLocaleData after dynamically loading a locale file.","solutions":["Ensure the locale's messages are loaded and registered via format.registerLocaleData(locale, messages) before formatting.","Use a locale that is bundled/registered, or fall back to the default locale when the requested one is unavailable.","Check format.hasLocale(locale) (or the registered set) before requesting the locale."],"exampleFix":"// before\nconst out = format.formatSomeMessage(...); // with unregistered locale set\n\n// after\nawait loadLocaleMessages(locale).then(msgs => format.registerLocaleData(locale, msgs));\n// now formatting in `locale` is safe","handlingStrategy":"validation","validationCode":"if (format.hasLocale(locale)) {\n  format.setDefaults({locale});\n} else {\n  await loadAndRegisterLocale(locale); // fetch + format.registerLocaleData\n}","typeGuard":"// format.hasLocale(requestedLocale) is the canonical guard; it returns true for\n// the default locale (always supported) and for any registered locale.\nconst ok = format.hasLocale(locale);","tryCatchPattern":"try {\n  return format.getFormatted(msg, locale);\n} catch (err) {\n  if (err.message.startsWith('Unsupported locale')) {\n    return format.getFormatted(msg, DEFAULT_LOCALE);\n  } else throw err;\n}","preventionTips":["Call format.registerLocaleData(locale, messages) before using a non-default locale.","Gate locale selection on format.hasLocale(locale).","Ensure bundle builds include (or dynamically load) the locale message JSON you intend to support."],"tags":["localization","locale","i18n","format"],"backgroundTag":null,"analyzedSha":"9515cd4e58ebed69f78742d932b501c2cab8ad8f","analyzedAt":"2026-08-13T06:28:10.346Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}