Humanizr/Humanizer · error · InvalidOperationException

Locale '{localeCode}' must define required top-level propert

Error message

Locale '{localeCode}' must define required top-level property 'locale'.

What it means

Parse requires a scalar `locale:` key naming the culture (CanonicalLocaleAuthoring.cs:77-79). Without it the document cannot be tied to a culture and the generator cannot wire the locale registry.

Source

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

            "dataUnitNonIntegralForm",
            "prepositionMode",
            "secondaryPlaceholderMode",
            "timeUnitGenders"
        ];

        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'.");
                }

View on GitHub (pinned to ffc2b77c0f)

Solutions

Add `locale: "<cultureCode>"` as the first top-level line.
Confirm it is a top-level scalar, not nested or a mapping.
Match the code to the filename (see error 4).

Example fix

# before
variantOf: "en"
surfaces:
  clock: {}
# after
locale: "en-GB"
variantOf: "en"
surfaces:
  clock: {}

Defensive patterns

Strategy: validation

Validate before calling

import yaml, sys
doc = yaml.safe_load(open(sys.argv[1], encoding='utf-8'))
assert isinstance(doc.get('locale'), str) and doc['locale'], 'missing top-level locale: scalar'

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: The YAML file has no `locale:` line, or `locale:` is present only as a nested key under surfaces.

Common situations: New file created from scratch without the locale header; the line was deleted during a merge; indentation put `locale:` under another block.

Related errors

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