Humanizr/Humanizer · error · InvalidOperationException

Locale '{declaredLocale}' must match file locale '{localeCod

Error message

Locale '{declaredLocale}' must match file locale '{localeCode}'.

What it means

The value of `locale:` must equal the locale code the generator associates with the file (CanonicalLocaleAuthoring.cs:81-85), which is derived from the filename/registry. A mismatch would silently bind the wrong culture, so the generator fails fast.

Source

Thrown at src/Humanizer.SourceGenerators/Common/CanonicalLocaleAuthoring.cs:83

        internal static CanonicalLocaleDocument Parse(string localeCode, string fileText)
        {
            var root = SimpleYamlParser.Parse(fileText);

            foreach (var property in root.Values.Keys.Where(static property => !SupportedTopLevelNames.Contains(property, StringComparer.Ordinal)))
            {
                throw new InvalidOperationException(
                    $"Locale '{localeCode}' defines unsupported top-level property '{property}'. " +
                    $"Supported properties: {string.Join(", ", SupportedTopLevelNames)}.");
            }

            var declaredLocale = root.GetScalar("locale")
                ?? throw new InvalidOperationException(
                    $"Locale '{localeCode}' must define required top-level property 'locale'.");

            if (!string.Equals(localeCode, declaredLocale, StringComparison.Ordinal))
            {
                throw new InvalidOperationException(
                    $"Locale '{declaredLocale}' must match file locale '{localeCode}'.");
            }

            var variantOf = root.GetScalar("variantOf");

            SimpleYamlMapping surfaces;
            if (!root.TryGetValue("surfaces", out var surfacesValue))
            {
                if (string.IsNullOrWhiteSpace(variantOf))
                {
                    throw new InvalidOperationException(
                        $"Locale '{localeCode}' must define required top-level property 'surfaces'.");
                }

                surfaces = new SimpleYamlMapping(
                    ImmutableDictionary<string, SimpleYamlValue>.Empty.WithComparers(StringComparer.Ordinal));
            }
            else

View on GitHub (pinned to ffc2b77c0f)

Solutions

Set `locale:` to exactly the filename's locale code.
Match case and separators (use the same BCP-47 form as the filename).
Re-run the build to confirm the values agree.

Example fix

# file: src/Humanizer/Locales/fr-CA.yml
# before
locale: "fr"
# after
locale: "fr-CA"

Defensive patterns

Strategy: validation

Validate before calling

import os, sys, yaml
path = sys.argv[1]
expected = os.path.splitext(os.path.basename(path))[0]
doc = yaml.safe_load(open(path, encoding='utf-8'))
assert doc.get('locale') == expected, f"locale: must be {expected}, got {doc.get('locale')!r}"

Prevention

Author locales against the canonical schema; the error message lists the exact allowed names.
Run `dotnet build src/Humanizer/Humanizer.csproj` locally so the generator reports locale errors before push.
Copy an existing compliant locale file as your template rather than writing YAML from scratch.

When it happens

Trigger: Copying fr.yml to fr-CA.yml but leaving `locale: "fr"`; renaming a file without updating the scalar; casing differences (en-gb vs en-GB) since the comparison is ordinal.

Common situations: Creating a regional variant by duplicating a base locale; locale code renamed in CI but YAML not updated.

Related errors

AI-assisted analysis of Humanizr/Humanizer@ffc2b77c0f (2026-08-13). Data as JSON: /api/errors/2ed04d68bde5350a. Report an issue: GitHub.