{"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":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/install/request.js","lineNumber":99,"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":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/install/request.js#L81-L117","documentation":"Thrown by normalizeInstallRequest() when a locale was supplied but is absent from the LOCALE_ALIAS_TO_COMPONENT_ID map. The map is the authoritative allowlist; anything else is rejected before any install planning happens.","triggerScenarios":"Passing `--locale fr` (French not shipped), `--locale en` (English is the default, not a translation), or a malformed value like `--locale zh_cn` (underscore vs hyphen).","commonSituations":"Assuming a locale exists because the language is common; using an underscore separator; copy-pasting an IETF tag that ECC does not alias.","solutions":["Call listSupportedLocales() (or check the install-manifests module) to see the exact accepted values for your ECC version.","Use the exact alias string the map expects (commonly hyphenated forms like zh-CN, zh-TW, ja-JP).","If you need an unavailable locale, contribute a translation rather than passing the unsupported code."],"exampleFix":"# before\nnpx ecc install --locale fr --target claude\n# after\nnpx ecc install --locale zh-CN --target claude","handlingStrategy":"validation","validationCode":"const { listSupportedLocales, LOCALE_ALIAS_TO_COMPONENT_ID } = require('../install-manifests');\nfunction isSupportedLocale(locale) {\n  return Boolean(locale) && Object.prototype.hasOwnProperty.call(LOCALE_ALIAS_TO_COMPONENT_ID, locale);\n}\n// before calling normalizeInstallRequest:\nif (options.locale && !isSupportedLocale(options.locale)) {\n  throw new Error(`Locale '${options.locale}' is not supported. Supported: ${listSupportedLocales().join(', ')}`);\n}","typeGuard":"function isSupportedLocale(locale, aliasMap) {\n  return typeof locale === 'string' && Object.prototype.hasOwnProperty.call(aliasMap, locale);\n}","tryCatchPattern":"try {\n  request = normalizeInstallRequest(options);\n} catch (e) {\n  if (/^Unsupported locale:/.test(e.message)) {\n    const supported = listSupportedLocales();\n    if (!options.locale && options.config?.locale) options.config.locale = supported[0];\n    request = normalizeInstallRequest({ ...options, locale: supported.includes(options.locale) ? options.locale : null });\n  } else throw e;\n}","preventionTips":["Always source the locale allowlist from listSupportedLocales() rather than hardcoding it.","Use exact hyphenated forms (zh-CN, not zh_CN or ZH-cn).","In UI dropdowns, populate options from the same function so users cannot pick an unsupported value."],"tags":["cli","locale","validation","install"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}