Label Files

Label files are the localisation mechanism in D365 F&O. Every user-facing string in the application — form captions, field labels, button text, error messages, report titles — should be stored as a label rather than hard-coded text. Labels enable the same application to run in any supported language without code changes.

A label file is an AOT object (AxLabelFile) that contains a collection of key-value string pairs for a specific language. Each label is identified by a label ID in the format @LabelFileId:LabelKey (e.g., @SYS4), and the runtime resolves it to the text in the user's session language.

---

How Labels Work

Each label file represents one language for a given label file ID. When you create a label file ID called MyLabels, you create one AxLabelFile per language you support:

AOT Object Name	Label File ID	Language	Physical File
MyLabels_en-US	MyLabels	en-US (English)	MyLabels_en-US.label.txt
MyLabels_de	MyLabels	de (German)	MyLabels_de.label.txt
MyLabels_fr	MyLabels	fr (French)	MyLabels_fr.label.txt

A single label ID — for example @MyLabels:InvoiceTitle — resolves to:

• "Invoice" when the session language is English
• "Rechnung" when the session language is German
• "Facture" when the session language is French

The framework resolves the correct text automatically based on the user's language preference.

---

Best Practices

Microsoft Best Practices for Labels

1. Always use labels — never hard-code user-facing strings in X++ code, form properties, table field labels, menu item labels, or any other metadata property that accepts a label reference.
2. One label file per model — create at least one label file for each model in your solution. This keeps label management organised and avoids cross-model dependencies.
3. Use descriptive keys — label keys should be meaningful (e.g., InvoicePosted, VendorNotFound) rather than auto-generated numeric IDs.
4. Provide translations — for each label file, provide localised versions for every language your deployment supports.
5. Reuse labels — before creating a new label, search existing label files for an equivalent string. Reusing standard labels (e.g., from @SYS) reduces translation effort.
6. Include comments — when creating labels, add a comment describing the context where the label is used. Translators use comments to produce accurate translations.

---

Creating a Label File

In Visual Studio

1. Right-click your project → Add → New Item → Labels → Label File.
2. Enter the Label File ID (e.g., MyLabels). This ID is the prefix for all labels in this file.
3. Select the primary language (e.g., en-US).
4. The label file is created in your model's folder.

Adding Labels

Open the label file editor in Visual Studio:

1. Double-click the label file in Solution Explorer.
2. Click New Label to add an entry.
3. Enter the Label ID (key), the Label text, and an optional Comment.
4. Save the file.

Adding Languages

To support additional languages:

1. Right-click the label file → New Language.
2. Select the language code (e.g., de, fr, ja).
3. A new label file object is created for that language.
4. Translate each label in the new language file.

---

Using Labels in Code

In X++

In Metadata Properties

Label references are used throughout AOT metadata properties:

Standard Label File IDs

Microsoft uses several label file IDs across the standard application:

Label File ID	Module / Area	Description
SYS	System-wide	Core system labels (e.g., @SYS4 = "Name")
SYP	System-wide	Additional platform labels
SCM	Supply chain management	SCM module labels
General	General	Common labels used across modules
HRM	Human resources	HR module labels

---

Label File Structure

The physical label file is a plain text file with the extension .label.txt. Each entry has the format:

For example:

warning

Never edit label files directly in a text editor in production scenarios. Always use the Visual Studio label editor, which handles file encoding, concurrent access, and label ID uniqueness validation.