3.3 Multilanguage Development with XLIFF & Translation Files

Microsoft Dynamics 365 Business Central Developer MB-820

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Business Central Architecture & Platform Foundation

1.1 Business Central Architecture & Extensions Model 1.2 Customization Lifecycle: Cloud (SaaS) vs. On-Premises 1.3 Base Application, System Application & AppSource

2 Chapter 2: Development Environment & Configuration

2.1: Development Environment Setup: VS Code, AL: Go! Projects & Sandboxes 2.2: AL Configuration Files: app.json & launch.json Parameters 2.3: Multi-Root Workspaces & Project Dependencies

3 Chapter 3: Extension Lifecycle: Debugging, Deployment, Multilanguage & Maintenance

3.1 Debugging & Snapshot Debugging in Visual Studio Code 3.2 Extension Deployment & Schema Synchronization Modes 3.3 Multilanguage Development with XLIFF & Translation Files 3.4 Extension Maintenance, Deprecation & Breaking Changes

4 Chapter 4: Tables, Table Extensions & Data Modeling

4.1: Building Tables, Fields, Keys & Data Types 4.2: Table Extensions & Table Modifications 4.3: FlowFields, FlowFilters & Table Relations 4.4: Enums, Enum Extensions & Extensible Types

5 Chapter 5: Pages, Page Extensions & Role Centers

5.1: Page Types, Anatomy & Control Structure 5.2: Building Card, List & Document Pages 5.3: Page Extensions & Page Customizations 5.4: Role Centers, Headlines & Cue Data Modeling

6 Chapter 6: Reports & Document Generation

6.1 Report Architecture, DataItems & Dataset Design 6.2 Report Layouts: RDLC, Word, Excel & Multilanguage 6.3 Document Reports & Request Page Programming 6.4 Processing-Only Reports & Report Substitutions

7 Chapter 7: XMLports & Data Exchange

7.1 XMLport Architecture, Formats & Properties 7.2 XMLport Node Hierarchy, Triggers & Stream Manipulation

8 Chapter 8: Codeunits, Events, Triggers & Interfaces

8.1 Codeunit Types, Execution & SingleInstance Codeunits 8.2 Events, Publishers, Subscribers & Event Isolation 8.3 Interfaces, Polymorphism & Dynamic Codeunit Invocation 8.4 Installation & Upgrade Codeunits, Data Transfer & Archive

9 Chapter 9: Entitlements, Permissions & Queries

9.1 Permission Sets & Permission Set Extensions 9.2 Inherent Permissions, Inherent Entitlements & Security Scoping 9.3 Query Objects: Joins, Aggregation & Query as Report Data Source

10 Chapter 10: UI Customization, User Assistance & Onboarding

10.1 Profile Objects & Custom Page Views in AL 10.2 User Assistance: ToolTips, Teaching Tips & In-App Tours 10.3 Assisted Setup, Guided Experience & Onboarding Checklists

11 Chapter 11: Business Central Design Patterns & Data Process Model

11.1 Functional Table Types: Master Data, Supplemental & Setup Patterns 11.2 Document Standards: Header, Line, History & Journal Architectures 11.3 Data Process Model & Posting Routine Architecture

12 Chapter 12: AL Language Fundamentals, Data Types & Variables

12.1 AL Syntax, Variable Scope, Primitive & Complex Data Types 12.2 Expressions, Control Flow Statements & Built-in Functions 12.3 Access Modifiers (Public, Internal, Local) & Code Scoping

13 Chapter 13: Data Manipulation, Streams & Error Handling

13.1 Record Operations: Get, FindSet, ModifyAll & Filter Functions 13.2 Streams, File Management & TempBlob 13.3 Error Handling: ErrorInfo, TryFunctions & Collectible Errors

14 Chapter 14: Testing, Test Toolkit & Automation

14.1 Testing Architecture & the Test Toolkit 14.2 Authoring Test Codeunits & UI Handler Functions

15 Chapter 15: Telemetry, Performance Optimization & Analyzers

15.1 Telemetry Configuration & Azure Application Insights 15.2 Custom Telemetry Signals with Session.LogMessage & KQL 15.3 Performance Profiler, SetLoadFields & Query Optimization 15.4 AL Analyzers: CodeCop, AppSourceCop, UICop & PTECop

16 Chapter 16: REST Web Services & JSON in AL

16.1 HttpClient, HttpRequestMessage & REST API Consumption 16.2 JSON Processing: JsonObject, JsonArray, JsonValue & JsonToken

17 Chapter 17: API Pages, OData, Read Scale-Out & OAuth

17.1 API Pages (PageType=API), OData Web Services & REST Endpoints 17.2 Bound and Unbound OData Actions with [ServiceEnabled] 17.3 Read Scale-Out Architecture & DataAccessIntent Configuration 17.4 Microsoft Entra ID App Registrations & OAuth 2.0 Integration

3.3 Multilanguage Development with XLIFF & Translation Files

Key Takeaways Explain This Topic AI

Multilanguage support in Business Central AL is standardized on XML Localization Interchange File Format (XLIFF version 1.2), completely replacing legacy CaptionML and TextConst syntax.

Configuring "features": ["TranslationFile"] in app.json instructs the AL compiler to auto-generate the base developer translation file <AppId>.g.xlf in the ./Translations directory during compilation.

Target translation files must follow the naming convention <AppName>.<CultureCode>.xlf using RFC 4646 / BCP-47 culture identifiers (e.g., ContosoApp.es-ES.xlf, ContosoApp.fr-FR.xlf).

In XLIFF translation files, localized strings are defined within <trans-unit> elements inside the <target> node with state="translated" indicating production readiness.

AL Label variables support Comment (providing contextual guidance and parameter token explanations), MaxLength (enforcing UI and database field bounds), and Locked = true (excluding strings from translation).

Last updated: August 2026

3.3 Multilanguage Development with XLIFF & Translation Files

Microsoft Dynamics 365 Business Central is deployed globally across dozens of localized countries and languages. In modern AL extension development, multilanguage capabilities are decoupled from source code logic through the XML Localization Interchange File Format (XLIFF v1.2) . Rather than embedding multi-language strings directly inside AL objects using legacy properties (such as CaptionML ), developers define baseline strings in AL and generate standardized XML translation files for localizers.

1. Enabling Translation File Generation in app.json

To activate automatic translation file extraction, the extension manifest ( app.json ) must include the "TranslationFile" feature flag inside the "features" array: {

"id": "b3a2e1d0-4c5b-6a7f-8e9d-0a1b2c3d4e5f",
"name": "Contoso Quality Management",
"publisher": "Contoso Ltd.",
"version": "1.0.0.0",
"brief": "Quality control inspections and checklists",
"features": [
"TranslationFile"
],
"idRanges": [
{
"from": 50100,
"to": 50149
}
]
}
The Generated Translation Base File ( .g.xlf )

When "TranslationFile" is configured, building the project ( Ctrl+Shift+B or F5 ) causes the AL compiler to parse all AL source files and automatically generate a base translation file in the Translations directory:

File Name: <AppName>.g.xlf (or <AppId>.g.xlf )

Purpose: Serves as the master developer translation baseline. It contains every localized property ( Caption , ToolTip , InstructionalText , PromotedActionDescription ) and every Label variable declared in the extension.

Read-Only Nature: Developers must never manually edit .g.xlf . The AL compiler regenerates and overwrites this file on every compilation.

Loading diagram... XLIFF Multilanguage Build & Translation Workflow

2. Anatomy and Structure of XLIFF 1.2 Translation Files

XLIFF files are structured XML documents containing translation units ( <trans-unit> ). Each unit represents a distinct translatable UI string.

Target File Naming Convention

Target translation files must be created in the Translations folder alongside the .g.xlf file and named according to RFC 4646 / BCP-47 language-culture tags:

ContosoApp.es-ES.xlf (Spanish - Spain)
ContosoApp.es-MX.xlf (Spanish - Mexico)
ContosoApp.fr-FR.xlf (French - France)
ContosoApp.de-DE.xlf (German - Germany)
ContosoApp.da-DK.xlf (Danish - Denmark)
Detailed <trans-unit> XML Structure

Below is an excerpt from a target translation file ( ContosoApp.es-ES.xlf ): <?xml version="1.0" encoding="utf-8"?>

<file datatype="xml" source-language="en-US" target-language="es-ES" original="Contoso Quality Management">
<body>
<group id="body">

<trans-unit id="Table 50100 - Field 50101 - Property 2879877212" size-unit="char" translate="yes" xml:space="preserve">

<source>Inspection Status</source>
<target state="translated">Estado de inspección</target>
<note from="Developer" annotates="general" priority="2">Status of the quality inspection checklist</note>

<note from="Xliff Generator" annotates="general" priority="3">Table Inspection Header - Field Status - Property Caption</note>

</trans-unit>
<trans-unit id="Codeunit 50105 - NamedType 1245896321" size-unit="char" translate="yes" xml:space="preserve">
<source>Do you want to post inspection %1 for item %2?</source>
<target state="translated">¿Desea registrar la inspección %1 para el producto %2?</target>
<note from="Developer" annotates="general" priority="2">%1 = Inspection No., %2 = Item Description</note>

<note from="Xliff Generator" annotates="general" priority="3">Codeunit Inspection Post - NamedType ConfirmPostQst</note>

</trans-unit>
</group>
</body>
</file>
</xliff>
Key XLIFF Elements & Attributes Explained

<file source-language="en-US" target-language="es-ES"> : Declares the base source language and the target destination language.

<trans-unit id="..."> : Unique identifier generated by the compiler combining object type, ID, element type, and property hash.

<source> : The original text authored in AL.

<target state="..."> : The localized text. The state attribute indicates the localization lifecycle stage:

state="new" : Newly extracted string; untranslated.

state="needs-translation" : Flagged for translator action.

state="needs-review-translation" : Translated by automated machine translation; pending human review.

state="translated" : Finalized, verified translation ready for production packaging.

state="final" / state="signed-off" : Approved by localization quality assurance.

<note from="Developer"> : Context notes provided in AL via the Comment property.

<note from="Xliff Generator"> : Automatically generated metadata indicating the source AL object, field, and property.

3. Localizing AL Objects: Captions, ToolTips, and Labels

To ensure professional translations and avoid truncated strings on mobile or desktop interfaces, AL provides robust property syntax for UI strings.

Table and Field Localization Syntax table 50100 "Inspection Header"
{
Caption = 'Inspection Header';
DataClassification = CustomerContent;

fields
{
field(1; "No."; Code[20])
{
Caption = 'No.';
ToolTip = 'Specifies the unique identifier for the quality inspection.';
}
field(2; "Item No."; Code[20])
{
Caption = 'Item No.';
TableRelation = Item;
ToolTip = 'Specifies the inventory item being inspected.';
}
field(3; "Inspection Date"; Date)
{
Caption = 'Inspection Date';
ToolTip = 'Specifies the date when the inspection was conducted.';
}
}
}
AL Label Data Type Syntax with Comments and MaxLength

When defining message strings, confirmation dialogs, or error texts in codeunits and pages, always use the Label data type with explicit Comment and optional MaxLength arguments: codeunit 50102 "Inspection Management"

{
var
// Placeholders %1, %2 documented for translators
ConfirmPostQst: Label 'Do you want to post inspection %1 for item %2?',
Comment = '%1 = Inspection Document No., %2 = Item Description',
MaxLength = 100;

InspectionSuccessMsg: Label 'Inspection %1 was successfully posted.',
Comment = '%1 = Inspection Document No.';

MissingResultsErr: Label 'You must record at least one inspection measurement before posting.',
Comment = 'Validation error when inspection lines are empty',
MaxLength = 120;
}
Why Comment and MaxLength are Crucial for MB-820

Placeholder Disambiguation: In English, word order may place %1 before %2 . In languages like German or Japanese, grammatical syntax often requires reversing the placeholders (e.g., %2...%1 ). Explaining each token in Comment prevents severe translation errors.

UI Truncation Prevention: Specifying MaxLength alerts translators when translating into verbose languages (e.g., German, Finnish) that strings must fit within designated screen real estate or report column limits.

4. Translation Synchronization & Fallback Hierarchy

When AL source code changes (such as adding new fields or modifying label text), rebuilding generates an updated <AppName>.g.xlf . Developers use translation synchronization tools (such as the XLIFF Sync extension or automated localization pipelines) to merge new <trans-unit> entries into existing target .xlf files without overwriting existing <target> translations.

Runtime Language Fallback Resolution

When a user accesses Business Central in a specific language (e.g., Spanish - Mexico es-MX ):

The runtime checks for an exact dialect match ( ContosoApp.es-MX.xlf ).

If not found, it falls back to the parent regional language ( ContosoApp.es-ES.xlf or es ).

If no Spanish translation exists, it falls back to the base application language defined in the AL source code ( en-US ).