What causes "Could not canonicalize the locale ID: %s. Error: %s" in nodejs/node?

Verify the locale ID follows BCP 47 / ISO 639 format: language_Script_REGION_VARIANT

Could not canonicalize the locale ID

Error message

Could not canonicalize the locale ID: %s. Error: %s

What it means

During XLIFF XML output generation, genrb calls uloc_canonicalize() to normalize the locale ID extracted from the resource bundle filename. If canonicalization fails (returns a UErrorCode failure), the locale ID is malformed or unsupported, and the tool exits the process. Canonicalization normalizes locale ID variants, keyword ordering, and alias resolution.

Solutions

Verify the locale ID follows BCP 47 / ISO 639 format: language_Script_REGION_VARIANT
Check the filename or -l option value for typos or non-standard codes: `locale -a | grep <prefix>`
Remove invalid extension keywords from the locale ID
Test the locale ID with ICU's uloc_getName() in a small C program to isolate the canonicalization failure
Use a known-valid locale ID from the IANA language subtag registry

Example fix

// before: invalid locale ID
file: test_XX_invalid.txt
// genrb -l 'test@bad' test.txt
// after: valid locale ID
file: en_US.txt
// genrb -l 'en_US' en_US.txt

Defensive patterns

Strategy: validation

Validate before calling

# Validate locale IDs before running genrb with --write-xliff
LOCALE="en_US"
# Check against ICU's known locale list (if icuinfo/uconv is available)
uconv -l 2>/dev/null | grep -q "^${LOCALE%%_*}$" || echo "WARNING: language code '${LOCALE%%_*}' may not be valid"
# Basic format check: language[_Script][_REGION][_VARIANT]
echo "$LOCALE" | grep -qP '^[a-z]{2,3}(_[A-Z][a-z]{3})?(_[A-Z]{2})?(_[A-Za-z0-9]{4,})?$' || echo "ERROR: malformed locale ID: $LOCALE"

Prevention

Use standard BCP 47 / ISO 639 locale IDs in resource bundle filenames
Validate locale IDs before passing them to genrb's -l option
Avoid non-standard locale codes or invalid extension keyword syntax
When in doubt, test the locale ID with ICU's uloc_getName() API

When it happens

Trigger: The locale ID derived from the resource bundle filename or the -l option fails uloc_canonicalize(). This can happen with completely malformed locale strings, locale IDs with invalid keyword syntax, or locale IDs containing characters that the canonicalization parser cannot handle. The tool calls exit(status) — this is fatal.

Common situations: Filename contains a non-standard locale code (e.g. 'zz_test.txt' where 'zz' is not a valid language); the -l option is set to a malformed locale string; locale ID with invalid extension keyword syntax (e.g. '@invalid' instead of '@key=value'); locale aliases that resolve to nothing in this ICU version.

Related errors

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/6d53a51a07a3dfe4. Report an issue: GitHub.

Appendix: source

Thrown at deps/icu-small/source/tools/genrb/wrtxml.cpp:212

    int canonLen = 0;
    /*int i;*/
    UErrorCode status = U_ZERO_ERROR;
    const char *ext = uprv_strchr(id, '.');

    if(ext != nullptr){
        pos = static_cast<int>(ext - id);
    } else {
        pos = idLen;
    }
    uprv_memcpy(localeID, id, pos);
    localeID[pos]=0; /* NUL terminate the string */

    canonCapacity =pos*3;
    canon = static_cast<char*>(uprv_malloc(canonCapacity));
    canonLen = uloc_canonicalize(localeID, canon, canonCapacity, &status);

    if(U_FAILURE(status)){
        fprintf(stderr, "Could not canonicalize the locale ID: %s. Error: %s\n", localeID, u_errorName(status));
        exit(status);
    }
    strnrepchr(canon, canonLen, '_', '-');
    return canon;
}

static const char* xmlHeader = "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n";
#if 0
static const char* bundleStart = "<xliff version = \"1.2\" "
                                        "xmlns='urn:oasis:names:tc:xliff:document:1.2' "
                                        "xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' "
                                        "xsi:schemaLocation='urn:oasis:names:tc:xliff:document:1.2 xliff-core-1.2-transitional.xsd'>\n";
#else
static const char* bundleStart = "<xliff version = \"1.1\" "
                                        "xmlns='urn:oasis:names:tc:xliff:document:1.1' "
                                        "xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' "
                                        "xsi:schemaLocation='urn:oasis:names:tc:xliff:document:1.1 http://www.oasis-open.org/committees/xliff/documents/xliff-core-1.1.xsd'>\n";
#endif

View on GitHub (pinned to 1b2de5e052)