{"record":{"id":"3baf4d3bd312917d","repo":"affaan-m/ECC","slug":"unsupported-locale-locale-supported-locales","errorCode":null,"errorMessage":"Unsupported locale: \"${locale}\". Supported locales: ${listSupportedLocales().join(', ')}","messagePattern":"Unsupported locale: \"(.+?)\"\\. Supported locales: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/lib/install/request.js","lineNumber":106,"sourceCode":"    }\n  }\n\n  return parsed;\n}\n\nfunction normalizeInstallRequest(options = {}) {\n  const config = options.config && typeof options.config === 'object'\n    ? options.config\n    : null;\n  const profileId = options.profileId || config?.profileId || null;\n  const target = options.target || config?.target || 'claude';\n  const moduleIds = validateInstallModuleIds(\n    dedupeStrings([...(config?.moduleIds || []), ...(options.moduleIds || [])])\n  );\n  const locale = options.locale || config?.locale || null;\n  const localeComponentId = locale ? LOCALE_ALIAS_TO_COMPONENT_ID[locale] : null;\n  if (locale && !localeComponentId) {\n    throw new Error(\n      `Unsupported locale: \"${locale}\". Supported locales: ${listSupportedLocales().join(', ')}`\n    );\n  }\n  if (locale && target !== 'claude' && target !== 'claude-project') {\n    throw new Error('--locale can only be used with --target claude or --target claude-project');\n  }\n  const requestedIncludeComponentIds = dedupeStrings([\n    ...(config?.includeComponentIds || []),\n    ...(options.includeComponentIds || []),\n  ]);\n  const includeComponentIds = dedupeStrings([\n    ...requestedIncludeComponentIds,\n    ...(localeComponentId ? [localeComponentId] : []),\n  ]);\n  const excludeComponentIds = dedupeStrings([\n    ...(config?.excludeComponentIds || []),\n    ...(options.excludeComponentIds || []),\n  ]);","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/install/request.js#L88-L124","documentation":"normalizeInstallRequest resolves the locale from options or config and maps it through LOCALE_ALIAS_TO_COMPONENT_ID. If a locale is provided but has no alias mapping (not in the supported set returned by listSupportedLocales()), it throws this error listing the supported locales.","triggerScenarios":"Calling normalizeInstallRequest (or runTests) with options.locale or config.locale set to an unmapped value: misspelled codes ('en-US' if only 'en' is mapped), wrong casing beyond alias handling, an entirely unsupported language, or an empty-but-truthy string.","commonSituations":"Typos in the locale code; using a region variant the installer doesn't ship ('fr-CA' when only 'fr' exists); a config file carrying a locale from another tool's naming scheme; copy-pasting a BCP-47 tag where only base aliases are supported.","solutions":["Use one of the locales listed in the error message (from listSupportedLocales()).","Try the base language code (e.g. `zh` instead of `zh-TW`) if only base aliases are mapped.","Fix casing/typos so the value matches an entry in LOCALE_ALIAS_TO_COMPONENT_ID.","Remove the locale from your config file if you didn't intend to install a translated component set."],"exampleFix":"// before\ninstall --target claude --locale zh-TW // if unsupported\n\n// after\ninstall --target claude --locale zh-CN // pick from the supported list in the message","handlingStrategy":"validation","validationCode":"const supported = listSupportedLocales();\nif (locale && !supported.includes(locale)) {\n  throw new Error(`unsupported locale \"${locale}\"; pick one of: ${supported.join(', ')}`);\n}","typeGuard":"function isSupportedLocale(l) { return Boolean(LOCALE_ALIAS_TO_COMPONENT_ID[l]); }","tryCatchPattern":"try {\n  const req = normalizeInstallRequest(options);\n} catch (e) {\n  if (e.message.startsWith('Unsupported locale')) {\n    console.error(`${e.message} — see listSupportedLocales() for valid codes.`);\n    return;\n  }\n  throw e;\n}","preventionTips":["Consult listSupportedLocales() before scripting a locale install.","Use base language codes unless a region alias is explicitly documented.","Strip stale `locale` keys from config files inherited from other tools.","Add a unit test that validates any user-supplied locale against the alias map."],"tags":["cli","locale","validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}