Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 06:36:55 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Refine self-improvement review guidance

Browse source 
Narrow IsHandled, label-scope, UI-handler, checkpoint, and bulk-operation guidance to evidence-backed false-positive boundaries.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
wenjiefan 2026-08-18 11:17:14 +02:00
parent 841b4e7cab
commit 5f1cff2fb6
21 changed files with 99 additions and 155 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -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;
}

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

@ -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;
}

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

@ -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.