{"record":{"id":"56e50dafad419cfb","repo":"Humanizr/Humanizer","slug":"locale-localecode-must-define-required-top-lev-56e50d","errorCode":null,"errorMessage":"Locale '{localeCode}' must define required top-level property 'surfaces'.","messagePattern":"Locale '(.+?)' must define required top-level property 'surfaces'\\.","errorType":"validation","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Humanizer.SourceGenerators/Common/CanonicalLocaleAuthoring.cs","lineNumber":94,"sourceCode":"\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                }\n\n                surfaces = new SimpleYamlMapping(\n                    ImmutableDictionary<string, SimpleYamlValue>.Empty.WithComparers(StringComparer.Ordinal));\n            }\n            else\n            {\n                surfaces = surfacesValue is SimpleYamlMapping surfacesMapping\n                    ? surfacesMapping\n                    : throw new InvalidOperationException($\"Locale '{localeCode}.surfaces' must be a mapping.\");\n            }\n\n            foreach (var surface in surfaces.Values)\n            {\n                if (!SupportedSurfaceNames.Contains(surface.Key, StringComparer.Ordinal))\n                {\n                    throw new InvalidOperationException(","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/Humanizr/Humanizer/blob/ffc2b77c0f30d2fb176875841424379319d0ae9b/src/Humanizer.SourceGenerators/Common/CanonicalLocaleAuthoring.cs#L76-L112","documentation":"A base locale (no variantOf) must define `surfaces:` (CanonicalLocaleAuthoring.cs:89-96). Only a pure variant — one declaring `variantOf:` — may omit surfaces and inherit everything. This prevents a culture being registered with no localizable content.","triggerScenarios":"A new top-level locale file has `locale:` but no `surfaces:` block and no `variantOf:`.","commonSituations":"Starting a brand-new locale and forgetting the surfaces block; stripping content during a refactor.","solutions":["Add a `surfaces:` mapping (even `surfaces: {}` is valid for a first stub) if the locale is standalone.","If the locale only overrides a parent, add `variantOf: \"<parent>\"` and omit surfaces.","Move any surface content you removed back under surfaces."],"exampleFix":"# before (standalone locale)\nlocale: \"de\"\n# after\nlocale: \"de\"\nsurfaces:\n  clock: {}","handlingStrategy":"validation","validationCode":"import yaml, sys\ndoc = yaml.safe_load(open(sys.argv[1], encoding='utf-8'))\nis_variant = bool(doc.get('variantOf'))\nassert is_variant or 'surfaces' in doc, 'a non-variant locale must define surfaces:'","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"}