{"record":{"id":"c8375e266d1f196b","repo":"Humanizr/Humanizer","slug":"locale-localecode-must-define-required-top-lev","errorCode":null,"errorMessage":"Locale '{localeCode}' must define required top-level property 'locale'.","messagePattern":"Locale '(.+?)' must define required top-level property 'locale'\\.","errorType":"validation","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Humanizer.SourceGenerators/Common/CanonicalLocaleAuthoring.cs","lineNumber":78,"sourceCode":"            \"dataUnitNonIntegralForm\",\n            \"prepositionMode\",\n            \"secondaryPlaceholderMode\",\n            \"timeUnitGenders\"\n        ];\n\n        internal static CanonicalLocaleDocument Parse(string localeCode, string fileText)\n        {\n            var root = SimpleYamlParser.Parse(fileText);\n\n            foreach (var property in root.Values.Keys.Where(static property => !SupportedTopLevelNames.Contains(property, StringComparer.Ordinal)))\n            {\n                throw new InvalidOperationException(\n                    $\"Locale '{localeCode}' defines unsupported top-level property '{property}'. \" +\n                    $\"Supported properties: {string.Join(\", \", SupportedTopLevelNames)}.\");\n            }\n\n            var declaredLocale = root.GetScalar(\"locale\")\n                ?? throw new InvalidOperationException(\n                    $\"Locale '{localeCode}' must define required top-level property 'locale'.\");\n\n            if (!string.Equals(localeCode, declaredLocale, StringComparison.Ordinal))\n            {\n                throw new InvalidOperationException(\n                    $\"Locale '{declaredLocale}' must match file locale '{localeCode}'.\");\n            }\n\n            var variantOf = root.GetScalar(\"variantOf\");\n\n            SimpleYamlMapping surfaces;\n            if (!root.TryGetValue(\"surfaces\", out var surfacesValue))\n            {\n                if (string.IsNullOrWhiteSpace(variantOf))\n                {\n                    throw new InvalidOperationException(\n                        $\"Locale '{localeCode}' must define required top-level property 'surfaces'.\");\n                }","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/Humanizr/Humanizer/blob/ffc2b77c0f30d2fb176875841424379319d0ae9b/src/Humanizer.SourceGenerators/Common/CanonicalLocaleAuthoring.cs#L60-L96","documentation":"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.","triggerScenarios":"The YAML file has no `locale:` line, or `locale:` is present only as a nested key under surfaces.","commonSituations":"New file created from scratch without the locale header; the line was deleted during a merge; indentation put `locale:` under another block.","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)."],"exampleFix":"# before\nvariantOf: \"en\"\nsurfaces:\n  clock: {}\n# after\nlocale: \"en-GB\"\nvariantOf: \"en\"\nsurfaces:\n  clock: {}","handlingStrategy":"validation","validationCode":"import yaml, sys\ndoc = yaml.safe_load(open(sys.argv[1], encoding='utf-8'))\nassert isinstance(doc.get('locale'), str) and doc['locale'], 'missing top-level locale: scalar'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["locale-authoring","yaml","source-generator","build","localization"],"backgroundTag":null,"analyzedSha":"ffc2b77c0f30d2fb176875841424379319d0ae9b","analyzedAt":"2026-08-13T21:42:34.584Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}