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: %s. Error: %s

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.

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)

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.