PracticeVideosBlogFlashcardsEspañol

Free exam prep

Microsoft Dynamics 365 Business Central Developer (MB-820)

Practice QuestionsStudy Guide

3.3 Multilanguage Development with XLIFF & Translation Files

Key Takeaways

  • 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"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <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

  1. 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.
  2. 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):

  1. The runtime checks for an exact dialect match (ContosoApp.es-MX.xlf).
  2. If not found, it falls back to the parent regional language (ContosoApp.es-ES.xlf or es).
  3. If no Spanish translation exists, it falls back to the base application language defined in the AL source code (en-US).
Test Your Knowledge

A developer needs to declare an internal URL endpoint string constant in AL that should NEVER be translated or exported into the generated XLIFF translation file (.g.xlf). How should the Label be defined?

A
B
C
D
Test Your Knowledge

Which configuration must be added to the app.json manifest file to instruct the AL compiler to automatically generate the base translation file (.g.xlf) during project compilation?

A
B
C
D
Test Your Knowledge

A development team is providing a French localization specifically for Canadian customers. Following standard Business Central RFC 4646 / BCP-47 conventions, what must the translation file in the Translations folder be named?

A
B
C
D
Test Your Knowledge

In an XLIFF 1.2 translation file (such as ContosoApp.es-ES.xlf), which XML element and attribute state indicate that a translated string is completed, verified, and ready for production runtime display?

A
B
C
D
Up Next

3.4 Extension Maintenance, Deprecation & Breaking Changes

Continue learning