Merge pull request #132 from microsoft/gggdttt-refine-self-improvement-guidance

Refine self-improvement review guidance

microsoft/knowledge/style/labels-declared-at-object-scope.bad.al

@@ -1,11 +0,0 @@
-codeunit 50262 "Sample Label Scope Bad"
-{
-    procedure LookupCustomer(CustomerNo: Code[20])
-    var
-        Customer: Record Customer;
-        GreetingMsg: Label 'Hello %1', Comment = '%1 = Customer Name';
-    begin
-        if Customer.Get(CustomerNo) then
-            Message(GreetingMsg, Customer.Name);
-    end;
-}

microsoft/knowledge/style/labels-declared-at-object-scope.good.al

@@ -1,13 +0,0 @@
-codeunit 50263 "Sample Label Scope Good"
-{
-    var
-        GreetingMsg: Label 'Hello %1', Comment = '%1 = Customer Name';
-
-    procedure LookupCustomer(CustomerNo: Code[20])
-    var
-        Customer: Record Customer;
-    begin
-        if Customer.Get(CustomerNo) then
-            Message(GreetingMsg, Customer.Name);
-    end;
-}

microsoft/knowledge/style/labels-declared-at-object-scope.md

@@ -1,30 +1,18 @@
 ---
 bc-version: [all]
 domain: style
-keywords: [label, scope, procedure, translation, localization, xliff]
+keywords: [label, scope, procedure, translation, localization, xliff, false-positive]
 technologies: [al]
 countries: [w1]
 application-area: [all]
 ---
 
-# Declare Labels at object scope, not inside procedure `var` blocks
+# Procedure-local Labels are valid
 
 ## Description
 
-`Label` is the AL declaration that participates in the translation pipeline: the build extracts every Label declared in an object into the `.xlf` file shipped to translators, and the runtime substitutes the localized value when the object is loaded. Translation tooling discovers Labels by walking the object's top-level declarations.
-
-Labels declared inside a procedure-local `var` block are still **compiled** as Label values, but their participation in localization is fragile: depending on the BC version, the build pipeline, and the translation toolchain in use, procedure-local Labels may be missed during XLIFF extraction, may be re-emitted with auto-generated keys that change between builds, or may not be addressable by reviewers triaging translations. The reliable, supported pattern is to declare every Label in the object's top-level `var` block.
-
-The same rule applies to all object types that own behavior: codeunits, pages, tables, reports, queries, and their extensions. For shared messages used by multiple objects, declare the Label in the most appropriate owning object and reference it — do not duplicate the literal across procedure-scoped declarations in several places.
+The AL language supports `Label` variables at both object and procedure scope. Microsoft documents the [Label data type](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-using-labels#label-data-type) without imposing an object-scope requirement, and the translation pipeline generates an XLF file containing [all labels used by the extension](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-work-with-translation-files#generating-the-xliff-file). There is no documented correctness or localization defect caused solely by declaring a Label in a procedure-local `var` block.
 
 ## Best Practice
 
-Move every `Label` to the object's top-level `var` block. Use the appropriate suffix (`Msg`, `Err`, `Qst`, `Lbl`, `Tok`, `Txt`) on the variable name so reviewers and the translation team can see at a glance what role the string plays. Pair non-translatable strings (URLs, JSON/XML fragments, integration tokens) with `Locked = true`, as covered by `label-locked-for-non-translatable.md`.
-
-See sample: `labels-declared-at-object-scope.good.al`.
-
-## Anti Pattern
-
-Declaring `Label` inside a procedure-local `var` block — `procedure Lookup() var GreetingMsg: Label 'Hello %1';` — couples the translatable string to one procedure, hides it from object-level review, and depends on a translation pipeline behavior that is not part of the AL language contract.
-
-See sample: `labels-declared-at-object-scope.bad.al`.
+Choose object scope when a Label is reused or when an established repository convention prefers central declarations; choose procedure scope when the Label belongs to one procedure. Do not report a correctness or localization finding solely because a Label is local. An explicit object-scope convention is at most a low-severity maintainability preference. This guidance applies equally to production and test apps: test code still needs localization where its strings are user-facing or translator-facing.